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IHIBODDCITOU 


1,0 lUIRODUCT'ION 


Your project mauagemeiit dei; ermines w}iich of ±he facilities cf DOEIOlfIC 
you can use {ie. which coraraands are available to you) . All of the 
DOHONXC facilities are oriented toward construction, maintenance and 
control of a data base containing project-related documentation data. 
This data base is called a dbcumentat icn unit. Data may include textual 
information, program source code and graphical information. Procedures 
are provided to limit access to either contents of the documentation 
•units or to the various DCMOljllC facilities, Th-ese security functions 
are under control of the local project management. In a.ddition. DOHONIC 
provides means for monitoring the construction and maintenance of the 
documentation units. 

The DOEOHIC system can be used in either a batch or a terminal-access 
environment, when operating in an interactive environment, you receive 
prompting messages in the case of inccm'pletely specified commands or in 
the case of incorrectly entered commands. Also, when in an interactive 
environment, you can interrupt process ing at any time to enter a' new 
command. 

You can type HEIP whenever you are unsure which command to use or how to 
‘use a particular command. ■ HELP is a special command that provides 
information on all the other DCEChlC commands. 

This manual explains how to use the DCECWIC command language. The 
manual consists of the following sections: 

1. Intro.duction 

2. What You Must Know To Use DOMONIC 

3. Eunctions-of DOMOUIC 

4- Entering and Manipulating Data 
5. Templates, and Data Definiticns 
6-. Recipes and Document Generation 

7. Initiating a Project 

8. Entering, and Changing Security Controls 

The first four sections must be hnown by all DOMOMIC users. Sections 5, 
7 and 8 describe functions normally use.d only by project management. 
Section 6 tells how to generate documents: 

This manual specifies whal commands to use in performing each of the 
functions mentio'ned above. Eo-r- more details on how to enter each 
command, refer-to the DOMOMIC CCMMAED BEEERERCE EARDAL. 
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2.0 WHIT YOU MUST KHCW TO USE EOMONIC 


You will be using DOMONIC either in a card-oriented envircnjnent or in . a 
terminal-oriented envircn ment 

In a terminal- oriented environment, you should hnow:, 

’^'How to enter information from the terminal. 

*How to use DOMCKIC ccomands. 

*How to interpret DOMCMIC messages- 
*How to use the HELP command. 

In a card-oriented -environment, you should know: 

>}=How to enter' information via cards. 

■ *How to use EOHCSIC commands. 

^How to interpret DOMOMIC messages. 

2.1 ENTERING IKEORMATICK FROM A TEEMIN-AI, 


All terminals supported by DCMONXC have a- typewriter keyboard, through 
which you enter information into the system. The various terminals 
supported by DOMCNIC do n.ot have identical keyboards. Some terminals do 
not have a backspace key; some do not all o-w lowercase letters. The 
features of each terminal as they apply to DOMONIC are described in 
Appendix A. 

Certain conventions apply to th-e use cf all terminals with' the DOHO.NIC 
system. They are: 

1. Ill lowercase letters typed on the keyboard are 
interpreted by the system as uppercase letters. 

For example, if 

system-abstract in t3 

was typed on the keyboard, the system interprets it as: 
SYSTiH-ABSTEACT IN T3 

The only exceptions are certain text-handling 
applications which allow both uppercase and 
lowercase letters to he entered from the 
keyboard . 

2. all messages sent tc the terminal by the system 
will be typed out in uppercase letters. 

Output from the previously mentioned text-handling 
applic-ations will be typed out both in uppercase 
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and lowercas-e if tfe teririnal has "that capability. 

If it does not, loMercase letters will be typed 
as the corresponding uppercase letters. 

The methods you may use tc correct your typing mdstahes are discussed in 
Appendix A since they are dependent on the type cf terminal -you are 
using. 

After you type a line and maie any necessary corrections, you can enter 
that line as follows: 

1. Press the lETUEN hey on an IBH 27^11 Communications terminal.. 

2. Press the PETUHK hey and LINE lEED keys on the teletype. 

All examples in this manual assume -operation with an IBM 27in 
Communications Terminal. Refer to Appendix A for information about the 
terminal you are using. 

NOTE: A null line (a line with no characters in it) can be entered by 
typing a semicolon in the first position and then pressing the hey used 
to enter a line (EETUEN hey on 2741) . Also you cannot make corrections 
to a command line once you have entered it. if the line was data, it 
can be changed using the EDIT command (described in the Section 4.0.) 

ALL COMMANDS AND SUBCOMMANDS MUST END HITS A SEMICOLCH. Sometimes a 
command will' not fit on one line and must he continued on the next and 
subsequent lines. THE SEMIC<3LG.N MUST APPEIB AT THE END' OE THE lAST IXNE 
QE THE COMMAND. The semicclcn convention must be observed even if all 
the information for the ccmmand fits cn one line. Also, you must still 
press RETURN to enter each line. 


2.2 ENTERING INFORMATION ERGM CARDS 


Hhen using DO'MOHIC in a card-oriented environment, all commands and’ data 
to be entered into the DOMCNIC system during a session must be prepared 
prior to using the system. The cards would normally be prepared with 
some off-line key-entry system such as a keypunch. After the cards have 
been prepared and checked for accuracy, they can be run as data cards in 
a batch' job deck. A batch job- deck b-egins with, a job card to identify 
the user, how long the job may take to execute and ether administrative 
information- Besides being a jcb control language card, the job card 
must conform to the installation’s format. The next cards are also JCL 
cards,. These cards will begin the execution cf the DOHONIC system^ fox 
IBM installations the JCl will consist of one ’EXEC’ card entering the 
catalogued procedure name that is necessary to invoke the system 
followed by one //SYSIN DD * card. 
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The DOMGBXC commana and dat-a cards are placed next in the deck 
immediately following the' //SYSIN DD * card. These cards are read one 
at a time by the DOMOEIC system just as if they were entered from a 
terminal where each card represents one line frcm a terminal. This 
implies that the first data card will contain a SIGEGN command and that 
the last card will be a SIGNOXF card. 

There are often slight differences between batch joi decks from one 
installation to another. Appendix B shows a sample batch job deck and 
explains what information is reguired for a typical installation. .The 
example given should te adapted to the conventions and procedures for 
your installation. Note that tie DGMONIC commands and data will not 
■ change., only the makeup of the rest of the deck may change. 

Certain conventions apply to the use of cards in the DOBCNIC system. 
They are; 

1. Each card represents one input line. 

2. Only those characters that can be punched on the 
card can be input. Normally this implies no lower- 
case letters. 

3. Since a card-oriented system is not interactive, 
there is no character or line deletion. 

4. All messages s-ent to you by the system will be 
printed in uppercase letters. Output from •, 
text— handling applications which have both upper- 
case and lowercase letters will print both 
cases if the proper type line printer 

is specified' in the GCl cards. If net, 
lowercase letters will be printed as the cor- 
, responding uppercase letters. 

Remember that each card entered in seguence in a card-oriented system 
corresponds to each line entered, in seguence, in a terminal- oriented 
system. Since all examples in this manual assume an IBB 2741 
Communications terminal, it is cnly necessary to notice the order in 
which information is reguired to be entered in order to prepare a 
corresponding card deck. 

If the information being entered dees net fit on one card, simply 
continue it on the next card. AFTER YOB HAVE ENTERED All THE 
INEORBATICN FOB THAT COBBAN’D, TYPE A SEHICCIQN (; ) . The semicolon 
convention must he observed even if the command you are inputting fits 
on one card. The sem'icolcn .is used by the system to delimit the end of 
a command. 
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2-3 BOW 10 USE DCHOHIC CQUaaUES 


You communicate with the BOBONI'C system by typing requests for worlc, 
commands, at the terminal. (All references to terminals apply to card 
input) , Different ccmmands specify different kinds of aork. You can 
enter data into the system, modify the data and retrieve it. You can 
specify data requirements and document specifications for a project. 

You can enter security orders for a project, ihe ccmmands make the 
facilities of the DGBONIC system available at your terminal- 

When you input a command to the system, it specifies which system 
function is to be performed, for some commands, the function involves 
several operations that ca-n be identified separately. One of the 
separately identifiable operations can be specified (after entering the 
command) by entering a -subcommand, A subcommand like a command is a 
request for work. The work requested is a particular operation within a 
function established by a command. 

The commands and subcommands recognized by BOHONIC, form the .BGHONIC ' 
command language. The command language is designed for easy use. Th.e 
command names and subcommand names are descriptive of the work they 
perform. The number of command names and subcommand names has bee-n kept 
to a minimum. You need only know those commands associated with the 
type of work you are to control. 

In addition to entering the name of a command or subcommand, you axe 
often required to input more information to further clarify the work you 
want performed. Operands (words or numbers that accompany the command 
names) are used tO' define the additional information. liany of the 
operands have default values which are used by the system if you choose 
not to input the operand with the command or subcomHand. Some operands 
axe required- If you neglect tc input a required operand, the system 
sends 'you a prompting message asking you to supply the requested 
operand. 

In the case of a card— oriented system, the prompting message will he 
output to the printer and the sjstem will expect the operand to be on 
the next .card read. 

The publication, DOHOHIC COKMBB BEE3EEBCE OWDAl, shows all operands 
for each command, indicates the default values where applicable, and 
describes h.ow to enter the commands. 

The D'0.a0NIC system allows you to abbreviate many of the. command names, •< 
subcommand names and operands. Yo.u can reduce the amount of typing' 
required by using defaults and abbreviations. The abbreviations and 
their use are 'discussed in the DGHCHIC CCHHAND EEfEBENCE HANDAI. 
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2.3.1 HHEN TO ENTER A CCEHI3AND OR SUECONHAND 


The system sends the message 
READY 

»hen it is ready to accept a new ccmmand. If the system is ready for 
you to enter a suicommand or data, the system wil’l output the name of 
the current command or subcommand, such ass 

■ EDIT 


or 


INPUT 

If instead of entering a subcommand, you wish to enter a command, enter 
the subcommands 


end; 

The subcom,mand END 3jill mate the READY message appear again. 

The system will accept commands until cue of the six commands (DEFINE 
DATA, EDIT, ERASE, GENERATE, SYSTEK, MCHITO.R, SECURITY) that have 
subcomraan.ds is entered. Subsequently , the system accepts only the 
subcommands of that command until a READY message is reguested by 
entering the END subcommand.' 


2.3.2 ROW TO ENTER A COMNASD OR SUBCCHMAND 


The system will send you a message when it is ready to accept a command 
or a subcommand.' Then you must: 

,1. Type the command or subccmmand name and theselected operands. 

2. Type a semicolon ( ;) at the end. 

3. Correct any typing mistakes with the character deletion character. 

NOTE: This only applies to terminals that 

have a character deletion character, 
such as tacxspace. The character 
deletion character worhs like backspace, 
erasing the last previously not 
erased character on the -line. 

4’. Press the RETURN key. 
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If ail 

1 . 


2 . 


3 . 

4. 


5. 


6 . 

7. 


the operands do not fit cn one line: 

Type the command or subccmmand name and the 
selected operands. 

If all of the selected operands do not fit 

on the lincj correct any typing mistakes on the line- 

press the SETUE'N k ey. 

Continue entering the operands'. If they do 
not fit on the next line, continue from 2. 

After all -the operands have been entered., 
type a semicolon {';i 

Correct any typing mistakes on the final, line- 
Press the BETDE.N key. 


Command names, subcommand names and cjerands can be typed in either 
uppercase or lowercase letters. If ycur terminal has lowercase' 
capability, you will usually find it more convenient to use lowercase. 
Since the system outputs in uppercase, this. all-OKS you to distinguish 
your input from the system’s messages in your listing. The examples in 
this manual follow this ccnvention." 


2.4 HOW TO INTEEPBET DOMCNIC MESSAGES 


There are four types of messages; - 
*Mode Messages . • 

. . =i^prompting Messages 
^Broadcast Messages 
*Inf ormational Messages 

*Hode Messages - . - 

A mode message informs you the system is ready to accept a command, 
subcommand or data. When the system is ready,' the mode message printed 
at your terminal is; • ‘ * ■ 

’ - BEADY ' ‘ 

If you enter a command that’ has subcommands, the syste'm will output a 
mode message that is the name of the current command, such as; 

EDIT 

If the subcommand, you entered expects data to be entered, the system 
will type out the mode message: 

INPUT 

The mode messages are displayed when the mode changes. 
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‘ ^Prompting Messages 

If yoa neglected to input: sene information oi if some information you 
input was incorrectly specified, the system will type a prompting 
message. Such a message reg.uests you to supply, or correct that 
information. The' following is an example of a prompting message:-' 

ENTE.B SCUBCECODE TYPE . 

You should respond hy entering the requested operand.: in this case the 
source code type, and hy pressing the EETUEN key to enter it. Eor . 
example, if the source code type is GEAPHICS you would respond to the 
prompting message as follows: 

ENTEE SGDECECODE TYPE 
graphics; 

^Broadcast Messages .. . 

Broadcast messages are messages of general interest to- users of the 
system. The system operator can hroa-ccast messages to .all users of the 
system or to any specified ’signed— on* user.. Usually these messages 
■will concern • system availability, Por example; 

HASA Will- HAIT OPEESTI-CES EOB P.H. IH 30 MIN. 

*Inf orma'tional Messages 

Informational messages tell you about the system’s status and your 
teifminal session. Eor example, an informational, message -may inform you 
when -document generation has ended, or how much time you have used. 
Informational messages do not require a response. In some cases, .an 
informational message may serve as a mode, message; for example, one that 
inform-s you of the end of a suheommand's operation also implies that you 
can enter another subcommand. 


2,5 HOW TO USE THE EEIP CCEH'AKD 


•The HEIP command- provides ycu with information aboui the function, 
syntax and operands of commands and subcommands. When you enter the 
HELP . comraa-nd, the system displays a brief discription of the desired 
function- If you need, help with the HELP .ccisroand, enter: - 

h elp h el-p ; 

If you are already farailar with the help command, you can enter the word 
HELP to receive a list of the valid commands for the system. For 
example: 


VALID COMMANDS ABE: SIGNCN, S3GNOFT, EDIT, SECUBITY, 
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MOMITOS, GENEEflTI, DIIIEE, ESasi, HEIE, END 

If you Jised help wllh one of the ccmmands, for instance SIGHON, you 
would enter: 

help slgnon; 

The system responds by typing cut the function, syntax and operands of 
the SIGNON command. You may however, enter the coiDmand followed by the 
word,, FUNCTICN, SYN'iax or OPIEIND, if you do not need help with all 
three- 


2.6 SIARTING a’HD ENDING h TEEMIN-AL SESSION 


This section describes the commands you ca-n use to: 
Identify yourself to the system,. 

* End your terminal session- 


2.6-1 IDENTIFYING YOUHSELE TO THE SYSTEM 


If you axe using a terminal, the first thing you must do is turn on the 
power according to instructions, pro-vi ded by your installation. In many 
cases, you will find an instruction sheet such as the one- shown in 
Figure 1 attached to the terminal. In the example shown in Figure 1, 
instructions 1 through 8 must he followed tc turn on the power and to 
establish the connection with the system- 

after you turn on the power, you must use the SIGHOK command to initiate 
use or or gain entry to the DOMCNIC system. You must supply, as 
operands of SIGNON, the user attributes assigned to you by your 
installation. Your user attributes are: 

1- User Id (required) — an eight character string that '■ 
identifies you to the system. 

2. - User-Password - (required) — an, eight character string that 

identifies the password that you are authorized to use. 

3. Uocumentati on-Unit— Id (reguired) — a character string 

•of maximum 30 characters that identifies the documentation unit 
you. are going to-wcrh on. 

Your user- attributes are recorded in the system, with the attributes of 
all other terminal users. When you- SIGNON, the system compares tlie 
attributes you specify in the SIGNCN command to the recorded attributes 
of each user to determine if you are an authorized user of the system. 


Page 14 



BO’MONXC USEE’S GUIDE 

WHS! 20D MUST KNOW TO USE DOHCNIC 


2.6.2 ENDING A TEEMINAI SESSION 


You can end your teruinal session iy entering the SIGNOFF cciamand. 

The SJGNOFF command removes you frcm active .status in the system tables, 
e.g, recipe, template, etc. 

After you' have entered the SIGNOFF command, the system will print out at 
your terminal ox on your listing the elapsed time of. tie session. 
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Terminal #4 

(Available 8:00 a.m. - 4:00 p. m. 

Fo-r additional time call S. -Warren ext. 220) 

1* Turn OiT/OFI switch to ON. 

2. sure the OOH/LCX switch is set to CCH. 

3. Remove handset fron telephone (.data unit). 

4. Press TAXK button on telephone. 

5. Dial ext. 225, 22-6, or 22 7. ' . 

6. 'Wait for a' high pitched lone- whe,n-you hear this tone you are in 
contact with the computer. If you get a busy signal or no answer, 
hang up and repeat from step 3‘ trying another, extension. 

7. Push the DATA button on. the telephone. If EATA button light goes 
off at any point during session, repeat from step 3. 

8- Enter SIGNON* command; 

signon user arseven password r7 dui nasadoc; 

(user-id), (password) • (documentation— un it-identifier) 

TO. If you a-xe in the interactive mode, th.e system will prcmpt you for 
your user-id, password and, documentation-unit-id if you 
fail to 'enter them. 

'11, SIGNON will respond with the time and data, if the above i-tems 
. pass the security test. 

12. If a fault is detected, an error message is returned and the user 
is' asked to enter SIGNON again. 

NOTE; Please turn CN/OFE switch to OEE after you enter SIGNOFF. 


FIGURE 1 


SANPIE INSTEUCTION SREET FOE A TEEHIS'AI 
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3.0 FUNCTIONS OF DOHONIC 

DOHONXC is oriented to support project documentation. This section 
summarizes terniiDolcgy relating to: 
aproject de-finition 
adata definition 
® document generation 
« dnta input 
•project control 
^security specification 
‘•system 

•Project Definition 

'Each project must have some- means of identifying itself and of keeping 
its data .separate from other projects. In the DOHONIC system a project 
is‘ called a DOCUIIENTATION UNIT. ’ The DOCDMEKTfiTION UNIT ID (DUI9 is. a 
unique name used to identify a specific IOCUaENTa,TION UNIT, ill data 
pertinent to :a project is associated with its DOCDHEKTATION UNIT. This 
.data might include management control information, description of 
project documentation, reguireraents, description of document generation 
reguirements, the documentation data itself along with other, 
administrative information, 

•Data Definition 

Each project manager must describe the data 'wbich is to be generated to 
complete the required documentatio-n package, for that project. The data 
definition for a documentation unit is called a TEHPLiTE. The template 
describes the data required -to be collected and made part of the 
documentation unit. ■ , 

• Document Genexation 

The forn and content of a document output from the system is specified 
with a RECIPE. The recipe describes which data in the documentation 
.unit is to be output^ in which order it is to be processed, whether it 
is to be passed through a ’driver’ for processing by a standard system 
program such as a compiler, and any special formatting controls. 

NOTE: Common libraries of both templates and recipes are maintained. 
Thus, a documentation unit, may make a copy of 'a template or a recipe 
from the common tom.plate library or from the common recipe library. The 
copy then becomes part of the documentation unit and is completely under 
change control of that documentation’ unit. 

•Data input. 

Documentation unit data, templates and recipes are input into the system 
through use of the editor. The editor allows you tc type in and 
interactively modify data- It recognizes lowercase characters. 
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♦Project Control 

Management of a project may benefit frcm reports profluced by the 
MONITOR. The moniter will be able to report on. terminal activity, 
current status of documentation data generation - 

• Security Specification 

local managers will need to control access. to -the various facilities of 
t-he DOMONie system- Some users will be allowed to specify recipes and 
templates while others may be allowed only to access documentation unit 
■data. The manager may control access through the SECURITY command of 
the system., 

£System 

In order to maintain the system,, systems analysts must be able to modify 
critical system tables. System co-mmands male it possible to male a 
documenta.tion unit Inown to the system and to manipulate data sets that 
will be used as the permanent storage fox the documentation units- 
access to the system, command is restricted. 
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4,0 ENTERING AND HANIPUXATING DATA 


Nearly all application systems are cciiceined with tie processing of 
data,. Therefoxej jou- should' learn how to input date and how to modify, 
store, and retrieve data after it has heen entered. Any group of 
related data that is input is known as a data unit. For example, a data 
unit may be a data element, template, recipe, -or documentation aid 
description (dccaid) . 

A data element may contains 

^Source commands, compose d . of programming lang^uage statements 
(Pl/1, COBOL, FORTRAN, .etc,) . 

*Text for descriptions-,, manuals, etc. 

*J0B. CONTROL <JCL) statements. 

Templates contain: 

^Statements in the data definition (template) language. 

Recipes contain: 

^Statements in the document generation (recipe) language. 

=5=Text for literals. 

Documentation Aid Descriptions contain: 

=^=Stat ements describing programs used for documentation and debugging 

Nhen you create a’ data u-nit, you must'-give it a name. The system uses 
the name to locate the' data unit whenever .you want to modify or retrieve 
it-' 

The . EDIT .command is used to create and edit data units. It operates in 
either of two modes: Input Mode cr Edit Mode. When you use the EDIT 
command to enter data into a data unit, you are using .the Input Mode. 
Hhen -you use the EDIT command to enter subccmmands io- edit the data in a 
data unit, you are using, the Edit Mode. 

In Input Mode, you can type a line of - data and then enter it into the 
data unit by pressing the terminal's carriage return kay or by entering 
another card. You can continue entering lines as long- as EDIT is 
operating in Inp.ut Mode. If you- enter 'a command or subcommand w.hile in 
Input' Mode, the system adds it tO' the data unit as input data. 

The system, will, assign a line number to each line as it is entered. 

Line numbers make Edit Mode operations -easier, since you refer to each 
line by its number., .You can ask the system to prompt you with the new 
line number at the start of each new input line. 
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After you finish entering data in the data unit, you can switch to Edit 
Mode by entering a semicolon and. striking the RETURN key or hy entering 
a card with a semicolon in the first column. 

The system lets you know you are- in Edit Eode by printing, the following 
message; 

EDIT 

In Edit Mode, you can enter subccmman d s to point to particular 'lines_ of 
the data unlt,^ to modify cr renumber lines, to add and delete lines, or 
to -control editing of input. 


When EDIT is operating in Edit Mode, it uses a current-line pointer to 
keep track of the next line of data to be processed. The operations you 
specify with the subcommands are performed beginning at the line 
specified by the pointer. For example, the DELETE -subcommand deletes 
the line indicated by the pointer. After a subcommand is executed., the 
sy st e m re post ti on s th e pointer . 

lou may want to reposition the’ pointer before a 'subcommand is executed. 
You can do so b.y .either of two methods: line number editing, or context 
editing. You can specify a line number as an" operand of a subcommand 
and the system will move the pointer to that line before it executes the 
subcommand, For context editing a set of subcommands (BOTTGE,, CHANGE, 
UP, DOIN', and El KD) allow you to move the pointer up or down a specified 
number of. lines, or to .find a line with a particular series of 
characters in it and move the pointer to it. After the pointer is 
positioned, you can enter the subcommand that performs the function you 
need. ' The subcommand may use an asterisk {*;) instead .of a line number 
to specify the line indicated by the pointer, or it may operate on the 
current line by default. 


After you finish editing- the data, you can -switch tc Input Mo.de by 
either of two methods; , . ■ 

•1. Entering ' the INPUT ox INSERT subcommand. 

2. Entering a semicolon and. striking the RETURN key or entering a 
card with a semicolcn in the first column. 

The system lets you know you are in Input Mode by printing the following 
messa-ge; 


input' 

You can terminate the EDIT command at a-ny time by changing to Edit Mode 
{if you axe not already in Edit Mode} and entering the END subcommand. 
The system then prints a READY message, and you can enter any command 
you choose. 
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If you .want to entex a blank line in youi data unit, you must enter a 
blank by pressing- tbe space bar and then the EETDRM key or by entering a 
blank card. lou can then enter lines after the blank line.- If you type 
a semicolon in the first column or enter a card, with a semicolon in the 
first column this will cause EDIT to change modes. 

•The rest of this section explains how- the subcommands of EDIT are used 
in? 

* Identifying the data unit. 

* Data unit naming conventicns. 

=5= Creating a data unit. 

* .Finding and positioning- the current line pcin ter. 

* Updating a data unit. 

* Renumbering lines of data, 
listing the contents of a data unit. 

* Storing a data unit. 

* Ending the EDIT functions. 

The followl'hg functions explained in this section are performed’ with 
commands other than EEIT: ' 

* Erasing,. a permanent data unit. 


4.1 IDENT-IEYIHG the data umt 


The EDIT command is’ used to specify the name of a data unit and whether 
you want to create it’ or edit it. When you enter a data unit name, the 
system will -scan the existing names for the .lame you entere-d. If the 
name does not exist, the system wiXL put you in th’e Input Mode, The 
following listing results when you enter a new da-ta. unit called 
NAS’AREPORT: 

READY 

edit nasa report; 

INPUT 

If you wish to edit a data unit named HODDLE, SUBSYSTEM. (DATA^ 
HAKAGEHENT,DFHDDATA) which has already been entered, the follosjing will 
result: 

READY 

edit mod- .ule . subsystem . (data-management ,dfnddata) ^ 

EDIT 
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4,2 EATA-TJEIT FA MI EG CCNVEN^IONS 


The jiajns you give a data unit stould follow certain conventions. A data 
Tijiit name can either be a template name, recipe name, docaid name or 
data element name. 

A template, recipe ana docaid name all have a maximum length of 30 
characters. The first letter must.be an alphabetic character while 
positions 2-30 may contain 'alphabetic characters, digits, dashes and 
underscores. Eo other characters including blanks are per missable. An 
example of a template name is^: 

SYSTEM-DATA-DEEINITION 

NOTEi A template name uniquely defines a template to the system. Within 
a template, individual data elements of the documentation unit are named 
by a long name. 

An example of a recipe 'name is:: 

NASA-SySTEH-EECIEE 
An example of a docaid name- is; 

FLOWCHARTEE 

A data element name consists of both data definition names and 
identifiers. 


NOTE; the rules for writing an ID (identifier) are: 

1, An IB has a maximum length of 30 characters. 

2, It must begin with an alphabetic character. 

3, Positions 2-3 0’ may contain cnly alphabetic characters, -dashes', 
digits and underscores'. Ho, -other characters are permissable. 

The rules for i-jrlting dat.a element names are: 

1. A short n’ame must begin with the letter ’T ’ 3nd be 
followed by an integer. T1— T3275S are the only acceptable 
short names. An example of a short name is: 

T rs 

2. A long name has a maximum length of 30 characters. it 
must begin with an alphabetic character and positions 2-30 
may contain only alphabetic characters, digits, dashes 
and underscores. Wo other characters are permissable. 
T'1-T32759 cannot be used as long names. They’ are reserved 
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for short names, 

SISIEM-ABS2SACI IH T3 

(long name) (short name) 

3„ A simple data element name is a long' name or short name. 

(Se.e rules 1 and 2.) An example of a simple data element 
is; 

T5 (short name) 

SYSTEM- ABSTRACT (long name) 

4. To qualify a data element name simply give the names- of the levels 
in the template hierarchy.. (See figure 3.) An example of a> 
qualified data element name. is: 

, UODUI-E-TITIE.. SDBSYSTEM-HODULES. SDBSYTEUS 

NOTE; As long as- the qualified name is uhig-ne/ , 
level names do not have to be given, A qualified name. 

• must be qualified, to the level nhich makes it unique, 
but an identifier must be given for each level with 
repeated occurrences whether or not the data definition 
name is given for that level.. 

When q-ualifying data element names, the data definition 
names must be depareted by periods and must be listed 
from the most specific to the least specific (from 
bottom to- top). For example in Eigure 3-, if you wanted 
'SUBSYTEH-AUSTBACT'*, you would enter: 

SD'BSYSTEH-AESTSACl-.SUBSYSTE^JS ' 

or 

You could enter just the short name, For example;- 
S UB S Y STE M- A E STB A CT . T 3.; 
or 


T1-4.T3; 

or 

T 1 4. SUBSYSTEMS; 

5. If any sub-level of a qualified name is a repeated occurrence. 
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additional identifiers are needed in order for the system to 
locate the desired level. 

An identifier fox each level of heixaxchy mrst be given from the 
least specific to the most specific. For example: 

SUBS YSTEM-NAHS.SUBSyETEK£{DATA-MANAGIMENT,D'FNDATA) 

or 

I 

T4.T3 {D1TA-.MANAGEM.ENI,UFN-DATA) 

If you want I-DESCEIETION {Figure 3) located on level T10, 
you vf-ould enter: 

1-DESCEIPTICK. MODULE-INEUaS. SDBSYS1:EM-H0DULES..SUBSISTSHS 
(DATA-MANAGEMEN3vDfNIAT.A ,C0 M HO-N-ABEA) 

or , - 

T10.18.15.T3 (D.ATA^I3AN'AGIHINa:„BFNUAiA,CQFiH0H-AEEA) 


or 

Any combination of long or short names: 


I-DESCEIPII CM' ( E A-T A-N AN AG EM ENT , DENE AT A ,COM MO K-A EE A) 

TIO {DATA-MANAGEMENT,DFNDATA, COMMON-AREA) 

I— DESCSIPTl'ON . T5 (r,ATA-HANJG_EMENT,DFNDATA, COMMON-AEEA) 
TT0'.T8<DATA-MANAGEMENT, DEiJEAT A ,COM MCN-ASEA) 


Identifiers must be enclosed within parenthesis, 
separated by commas and listed from left to right 
beginning with the most general to most specific. 
{Begin' at the top and work toward the bottom.) 


4. 3 CBEATING A, DATA UNIT 


You usually create a data unit when in the Input Mode of the EDIT 
command. you request Input Mode when one of the following is -done: 

1. You press the carriage return key after typing only a semicolon 
or a punched card is read with a semicolon, in the first column. 

2. You enter the INPUT subcommand.' 

NOTE: This subcommand initiates line count and increment, 

3. You enter the INSERT subcommand vith no operands. 
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AjftS'r entering the Irput Mode the syst.em sends you the following 
messag.e: 

- INPUT 

After this message is printed the systeiE . prints the first line number of 
your data unit if you have requested prompting. 'The first line number 
printed is 00010. Type the first line cf input- to the right of the line 
number and press the NETUEN key to enter ‘it. The system then prints the 
second line number., which is 00020, and. you may then enter your second 
line of input, and so forth. 

When you -reach the- end of the data, you enter a null line b-y typing a 
semicolcn and pressing the carriage return key or by entering a card . 
with a semicolcn in .the first column- You xfill then be in Edit Mode. 

You will also switch tp Edit Mode when there is no more space for lines 
to be inserted .into the data unit and reseguencing is not allowed or 
when an error is encountered when reading or writing the data unit. The 
following is an example of the above: 

READY 

edit module-inputs, subsystem-modules, subsystems (data manageroent,d write) ; 

INPUT 

00010^ enter— dwrite 

0002U- • move wsam-area-n umber to wsam-io-area, 

00 030^' get the working storage data entry 

00040 ' call ’wgtwsdat ’ ■ using ccb,cda 

00050 : 

EDIT 

In the example., . the line numbers have the stan-dard increment cf 10;. If 
you prefer a different increment, you can use the 'INPUT subcommand to 
change it. To do this you' must first request a switch to Edit Mode by 
entering a semicolon and’ then striding the carriace return oir entering a 
card with a semicolon in the first column, after you receive the INPUT 
message. Then enter the INPUT subcommand specifying the number of the 
•first line and the size of the i,ncxeinent. After entering, the INPUT 
subcommand, th.e system switches to Input Mode and prompts you »it,h the 
first line nunber. For example, to start with line 5 and use increments 
of 5, you could use the fcllowing seguence: 
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SEA-DI 

•edit module-inputs .subsystem— modules, su’bsys-tems (data— management ,d write) ; 
INPD3? 

0001 , 0 ; 

EDIl • 
input 5 5; 

INPUT- 

00005* enter-dwrite 

0,0010 -move wsam-are-a-number to wsa ra-io-area, 

000‘15* *** get fhe working storage data entry *** 

,00020 call 'sgtwsdat^ using ecl3,cda 

00025; 

. ED 13? 

You can create the same data unit in Id'it Mode. However, you most enter 
the line- numbers you wish' to- use. 

READY 

edit module-input s.su-bsYstem-mcdules, subsystems (data management, dwrite) ; 
INPUT ' ■■ ■ ■ 

00010 ^ 

EDIT 

5 enter-dwrite 

10 move wsam-area- number to wsam-io-ar ea , 

15 get the working storage data entry *** 

20 call 'wgtwsdat’' using ccb,cda 

MOTE^ Requesting an increment larger than 1,- makes it easier for you to 
insert lines in your data unit later cn. (See 'Section 4,5 for 
in-struction on how to insert lines in your data unit.) 


4.4 PINDING AND ECSITIOHING THE CURRENT LINE PCIKTEE 


Unless you use line numbers for all edit operations, you should kno^w how 
to find and reposition the current line pointer. These operations are 
explained in the following paragraphs. 

4.. 4.1 EINDING TS'E CURRENT LINE POINTER 


The location oi the current line pointer is determined by the last 
subcommand you entered, ' If you are editing an old data unit, the 
current line pointer is positioned at the, last line of the data unit 
upon initial entry into Edit- Mode. ■ The following figure' shows the 
location of the pointer at the end of each- subcommand. 
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EDIT SDBCOM MINDS 


ALTER 

BOTTOM 

CHANGE 

DELETE 


DOEN 


END 

FIND 

HELP 

INPUT 

rNSERT 

Insert/Eeplace 

/Delete 


LIST 

RENUM 

SAVE 

TABSET 

TOP 

UP 


VERIFY 


FIGURE 2 


VALUE OF POINTER AT END OF SDBGOMHAND 


Last line changed-. 

Last line (cr zero} for empty data 
units. 

Last line- change'd. 

Line prece-dinc deleted line (or zero 
if the first line of the data units 
has beed dele-ted<) .’ 

Line n relatve lines, telow the last 
line referred to, where n is the 
value of the, 'count' parameter, or 
bottom of- the data unit (or line 
zero fox empty data units). 

No .change. 

Line containing specified string, if 
any5 else, no change. 

No change, 

last line entered. 

Last line entered. 

Inserted line cr replaced line or 
line preceding the deleted line if any 
(or zero, if no preceding line 
exists) . 

last line listed . , 

Same relative line. ’ . - - 

No change. 

No change. 

Zero value. 

Line n relative lines abo-ve the 
last line referred to, where n 
is the value cf the ’.count' 
parameter,, (or ling zero for empty 
data units) ,- 
No change'. 


VALUES OE LINE POINTER REFEREED TO BY AN ASTERISK 
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If you do not remember' 1:his inf crmaticn, you can use the IIST subcommand 
sjxth the * (asterisk) operand to find the line at which the pointer is 
positioned, Eor example: 

• list 

THIS IS NHEEE TEE CURRENT lIRE EOINIER IS POSITIONED 

Yon can also have the system’ display the line at. which the pointer is 
positioned every time the pointer changes as a result of the CHANGE, • 
TOP, E0TTOH-, UP, BONN, EIND an d^ DEIETE subccmmands. To do this enter: 

verify; 

The VERIFY subcommand is in effect until you enter it again with the OFF 
operand. For example: 

verify off; 

4.4.2 POSITIONING THE CURRENT I. INF POINTER 


ay- using the OP, DOWN, TOP, fiOTTCH and FIND subcom^mands, you can move 
the current line pointer. 

The UP subcommand moves the pointer a specified number of lines up,- 
relative to the beginning" of your data unit. For example, to move the 
poinrer so it refers to a line located five lines before the, location 
currently referred to, enter; 

'IP 5; 

The DOWN subcommand -moves the pointer a specified number of lines down, 
relative to the end of your da"ta unit. For example, to move the pointer 
so it refers to a line located 1-7 lines after the location currently 
referred t-o, enter; 

down 17; 

The TOP subcommand moves the pointer to the positicn preceding the first 
line of your data unit. TOP is -often used’ in combination with the, DOWN 
subcommand. For example, if you want the pointer to refer to the third 
line of your data unit, use the following sequence; . 

top; 
down 2; 

The BOTTOH subcommand moves the pointer to the last line of the data 
unit. 
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The TIND su’bcomraaua moves the pointer to a line that contains a 
specified sequence of characters. Tor example, to move the pointer to 
the line that contains SUESYSTEM-lf ABE, enter: 

find X subsystem-name; 

The inserted before ’subsystem’ is a special delimiter that marTcs 

the beginning of the s.eguence of characters the system has to locate. 
The special delimiter can be any character other than a number, blank, 
tab, or asterisk. The special delimiter must be placed next to the 
first character of the sequence you want to find- Any blanks inserted 
between .the special delimiter and the first character are considered to 
be' part of the sequence of characters. You must not use -the extra 
character in the character string. 

4-. 5 UPDATING A DATA UNIT ' 


Certain functions of the EDIT command allow you to update a data unit. 
For example, you may; 

1. Delete data from a data unit. 

2. Insert data in a data unit.. 

3. Replace data in a data unit. 

• -4. Change lines in a data unit. 

5. Renumber lines, of a- data unit. 

NOTE: The Insert/E eplace/Delete function inserts, replaces 

■pr deletes a line of data without indicating a subcommand 
name. If you want to insert or replace a line,, simply 
specify the location and fhe hew data. To delete a line, 
indicate the location. A line number or an asterisk 
should be used to specify the locati.cn. The asterisk 
tells' you that the location fo be used is pointed to by 
the line pointer within the system. By using the UP, DCW'N-, 

BOTTOH and FIND subcommands, you can change the line 
pointer. 

These functions are explained in the fcllow.ing paragraphs. 


4.5.1 DELETING DATA FROM A DATA UNIT 


If you want to delete only. one line, yon do .not heed a subccrnmnd. 
Indicate only th.e line number or -an asterisk. For example^ if you want 
to delete line 38, enter: 

38; 
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If you. 'wan-t. to delete the line indicated by the current line pointer, 
en ter : 


You can also use the CEIETE subcommand to perforin the same function. 
For example: 

delete 38 ; 


or 


del 

DELETE also aliens you to delete consecutive lines. To do so you can 
specify the line numbers of the first and last lines to be deleted, ox 
the number of 'lines to be deleted starting -with the line indicated 'with 
the current line pointer. For example, if you ^jant to delete all the 
lines between and including lines 9 and 64, enter: 

delete 9 64; 

If you want to delete 22 lines beginning with line 6 and the current 
line pointer is currently positioned at line 6, enter: 

delete * 2.2; 

If you want to delete all the lines in your data unit, use the TOP and 
DELETE subcommand in combination, specifying for DELETE a number of 
lines greater than the number of lines in your data unit or another 
asterisk. For example; 

top; 

delete 99999; 


or 


del ^ *; 

After the system deletes the lines you requested, the current line 
pointer is positioned at the line before the first deleted line. 

4., 5.2 INSERTING EAT A IN A DATA UNIT 


To insert only one line in a data unit, you do not need a subcommand; 
indicate only the line number. The line number referred to should not 
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exist. {That is, it-shoul6 fall between two nonconsecutive line numbers' 
in the aata unit.,) For example, -if you want to insert ’HOVE 3.1416 TO 
PI> as line 55 enter; • . 

55 move 3,1416 to pi^ 

The characters you want to enter must be Separated from the line number 
by a single blank,. Any additional blanks or commas- are considered to be 
part of the input data. You may opticnally use the tab key to separate 
characters from the line number ox asterisk. In this case all blanks. 
Including t-he first, resulting from the tab will be part of the input 
data. The number of blanks resulting from the tab is determined by the 
logical tab setting. The logical tab setting results from the TABSET 
subcommand or the default tab setting. . . 

To insert one line of data after the current line, use the I-NSEIT 
subcommand with the insert-data operand. For example: 

list 

. HOVE 3.1.416 TO 51 

insert' circum = 2 pi * radius 

The rules for separating data from line num-bers also apply for 
separating, inserted data from the subccmmand name. 

When you want to insert more than one line, use the INSERT or INPUT • 
subcommands. 

NOTE: The INSERT subcomia and increments each line by 1 and the INPUT 

subcommand increments each line by 1 0 . . ■ 

The INSERT' subcommand inserts one or more- lines of data following' the 
location pointed to by the current line pointer. If the data you are 
entering is longer than that line-, ycu will receive a m.essaoe informing 
you of a truncation. In order to add the extra data, you must insert a- . 
new line. 

Fox example, suppose you have the following data unit; 

BO 75 1=1 ,.10. 

EiEMNT (I) =ELEMNT (I) -4-2 
Y(d,I)=X(I,J) 

75 CONTINUE 

To insert three lines after the entry for Y =X (I, J) and before 75 

CONTINUE, you must first position the current line pointer at the third 
line. .Your listing would lock like this: • ' 


Page 31 



DOHOHIC USER’S GUIDE . 

ENTERING 'and MANJPUIATING DATA 


EDIT 
top; 
down 2 ; 
insert; 

INPUT 

■do 66 m-1^3 
a (m ) = X (X , j-) + el e amt ( ffi)- 
33 continue 
; (null line) 

EDIT 

You must enter a null line ty typing a semicolon and striking the 
carriage return key or by entering a card with a seio-icolon in the first 
column. A null line shifts the mode from Input to Edit. 

The INPUT subcommand is used in a manner similar to t.he INSERT 
subc^oramand . Use an asterisk in the INPUT subco.mmand' to indicate that 
the lines of input that follow are to be inserted in the location 
following the' current line pointer, Eor example, assume that you have 
the following data unit: 

DO 75 1=1',. 10 

EIEHHT (I)=E1ENNT (I) + 2 

Y(J,I)=Y(I,J) . . 

75 CONTINUE 

To insert four lines after the line f cr- Y { J ,1) = X (I , d) and before 75 
CONTINUE, enter:' 

EDIT ■ 
top;: 

down' 2; . 

input 

INPUT 

do 6 6 m=T,3 
a (ffl)=x (i, j) +elemnt (m)' 

33 continue 
; (null line) 

ED IT 

Note that after you" enter the INSERT cr the INPUT s'uhcomraand, EDIT 
changes to Input Mode. 

You can use the INPUT or INSERT subcommand to replace lines or to insert 
one or more lines of data between two existing lines of the data unit. • 
You can also specify a smaller increment for the new line numbers so 
that they fit between the line numbers of the existing lines by 
specifying the INSERT. subcommand, Eor example, suppose you have the 
following data unit: 
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RETDRR-CODS 

=0 — everything is okay, 

=1 — IDENTIFIER HOT GIVEN BY USEE. 

=2 — DATA .NAME IS VALIE. 

To replace -the.fhird and fourth lines, you iDUSt first position the 
current line pointer at the third line. 

EDIT 
top; 
down 2; 
input * r; 

INPUT 

=1 — too many operands^ 

=2 — invalid data name. 

; (null line) 

EDIT 

Your updated data unit would look like this: 

RETURN-CODE 

=0 — EVERYTHING IS GKAY . 

= 1 — TOO HANY OPERANDS. 

=2 — ^INVALID DATA NAME. 

In the following example, the data unit with line numbers is: 

00010 RETURN-CODE 

00020 EVERYTHING IS OKAY. 

00030 IDENTIFIER NOT GIVEN BY USER. 

00 040 DATA HAKE IS VAilD. 


To replace lines 30 and 40^ your listing should lock like the following 


EDIT 

input 30 

INPUT 

00030 

00040 

00050 

EDIT 


X ; 

= 1 — too many operan,ds. 

=2 — data name is invalid - 
; (null line) 


Y.our updated data unit will look like the following: 


00010 RETURN-CODE 

00020 =0 — EVERYTHING IS OKAY 

00030 =1 — TOO MANY OPERANDS. 

00040 =2 — DATA NAME’ IS INVAIIE. 


Page 33 



D0J30NIC USES^S GUIDE 
ENTERIHG AND EANIDU1ATI.NG^ CAIA 


You can also replace a line and insert additional lines. Fox example, 
assume the same data unit: 

00010 SETUSN-CODE 

00020 =0 — EVEBYTH'IHG IS 'OKAY, 

.00030 =1— IDENTIFIER NOT GIVEN BY USER. . 

00040 =2 — DATA NA-EE IS 1/AlIB. ' 

To replace line 30 and insert two lines with a line increment of 2, ycur 
listing should look like tie following: 

EDIT 

input 30 2 r ; 

INPUT 

00030 =1 — invalid change order number. 

00 0 32 too many operands.. 

00034 data name is invalid. 

00 036 ; (null line) 

EDIT 

Your updated data unit will look as follows: 

00010 RETURN- CODE 

00020 ■ =0 — EVERYTHING IS CKAY. 

00030 =1 — INVALID CHANGE ORDER NUMBER- 

00032 TCO MANY OEERANES. 

00034 DATA NAME IS ' IN V All I. 

00'040 =2 — DATA NAME IS VALID. 

To replace more than one line with a greater number of. lines, you can 
also use the DELETE subcommand ±o delete those lines and then use either 
INPUT or INSERT to insert the replacement lines. 

Use of the numbers subcommand causes the' line numbers to be printed each 
time the data is printed. This is. the. system default. It works in 
conjunction with the prompt feature of the input subcommand-. For 
example: 


numbers on; 


Use the CHANGE subccminand to change only part of a line or lines. Use 
the ALTER subcommand, an option of the CHANGE subcommand, to replace a 
single character with a hexadecimal number. For example, to change, the 
characters * SYSTEM S-TITUS ’ to »NASA REPORT' in line 16 of your data 
unit, enter; 

change 16 xsystem statusxnasa report; 
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■NOIE: since yon are replacing a 13 character string with an 11 

character string, the system antcmatically £guee 2 es up the line and 
justifies the line to the left. 

The- ’x' placed before the characters to be changed and the replacement 
characters is a special delimiter that marks the beginning of those 
sequences of characters. The special delimiter can be any character 
other than a number. Hank, tab, or, asterisk. Make sure the character 
you choose as a special delimiter does not appear in the sequence of 
characters you specify. If you leave blanks between the last character 
to be replaced and the special delimiter for the replacement characters, 
the blanks are considered part of the characters to be replaced. The . 
special delimiter need not appear at the end of the replacement 
characters unless other parameters are to follow - 

An asterisk may be used in .place of a- line number., Por example, if the 
change is in the line currently indicated by the current line pointer, 
enter: 

change *.xsystera statusxnasa report; 

You can have the system search fox a seg.uence of characters in a range 
of lines rather than in one line. You can indicate the range of lines 
by giving the numbers for the first and last lines of the range, or by 
indicating the current line pointer and the number of lines you want to 
have s-earched. Tor example, if the characters ’ SYSTEM STATUS* appear 
some.where between lines 1-0 and 18, enter: 

change TO T8 ?system statusYnasa report; 

If the characters appear within the 5 lin.es starting with the one 
indicated by the current current line pointer. 

change ^ 5 Ysystem statusYnasa report; 

t 

NOTE: the above examples find and change the first and only the first 
instance of the string ’SYSTEM STATUS'. 

You can change the sequence of characters every time it appears within 
the range of lines. To do this specify the ALL opeiand after the 
replacement sequence. The special delimiter must be used to end the 
replacement string before typing 'all'. Fox example, 

change 10 18 xsystem statusxnasa reportxall,; 


or 


change * 10 xsystem statusxnasa reportxall^ 
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If you desire, you car have the system find a segae'rce of characters ,ir 
a line and print that line up to those characters- You can then type 
neW’ characters to complete the line and enter the new line .when you 
press the carriage return "key. For example, assume you want to change 
the characters ^FRIDAY” to ^EGNDAY’ in the. following line; 

00018 PROJECT REPORT DDE TRIDfiY 

Your listing will looh like the following; 

change 18 /friday; 

00 018 PROJECT REPORT DUE Dionday 

If the characters you want to change are in line indicated by the 
current line pointer, your' listing would look like this: 

change =*= /friday; 

00018 PROJECT REPORT DUE monday ' ' 

You can also ask the system to print out a specified number of 
characters of a given line. Then you can enter the characters you want 
to replace the remaining characters in the .line. For example, you can 
ask that the first 15 characters of the line ’PROJECT REPORT FINISHED* 
be printed; 

change 18 15 ; 

0001.8' PROJECT REPORT finished 

You can have the system print the first^several characters of a range of 
lines. This is particularly useful when you want to change a column in . 
a table. For example, assume you have the following data unit. 


00010 SECURITY CHECK 

00*012 J. SHITH .. S2 

00 014 , N. SCHHICKER R6 

00016 1. ZUINONSKI Z9 ‘ 

00018 G JONES ■ J10 


If you want to change the data in the last column, which begins in 
position 21, enter; 


change 12 18 21 

5 


00012 .J. 

SHITH 

gsl 

00014 M. 

SCHHICKER 

ffis6 

00016 1. 

ZDINOWSKI 

zlO 

■00 018 G. 

JONES 

gj.5 


if you want to change the data in the last column and the current 
line pointer is at line 12, enter: 
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change ^ 
00012 

5 21; 
d- 

SMITH 

- jsl 

00014' 

M. 

SCH.MICKEB 

ms6 

00016 

L. 

ZOLNOESKI 

zlO 

00018 

G • 

JONES 

gjS 


You can insert a character seguence at tlie beginning of ±he line. Tor 
example, if line 22 of your data unit is as follows: 

00022 MISSILE SYSTEMS 

enter; 

change 22 xxnasa report of ; 
to obtain: 

00022 UASl lEPOETOE MISSILE SYSTEMS 

You can also delete a character sequence using the CHANGE subcommand. 
For example, to delete NASA from line 22 above, enter: 

change 22 xnasaxx ; 


or 


change 22 xnasax; 
to obtain: 

00022 REPORT OF MISSILE SYSTEMS 

4.6 FEH'UHBERIKG LIKES OF DATA 


You can use the REKDM subcommand to renumber the lines of a data unit. 
If you enter: 

renum; 

the system assigns new line numbers to all the lines of the data unit. 
The first line will be assigned the number 10 and subsequent lines will 
be incremented by 10. 

You can assign' a number to the first line of the data unit. For 
example, if you want the first line to have number 5, enter the 
following: 


Page 37 



DOaONIC USER1S GUIDE. 

ENTESIKG ANJD HAHIPOLATIHG D'AIA' 


renum 5 ; 

The remaining line numhers -will he 15, 25, 35, etc.. 

You can specify an incrsraeni; other than 10 in addition to the number of 

the first line. For example if y-ou Tjant the first line to be number 
one, and the^ remaining line numbers to increase- by 5, enter: 

renum .15; 

You can specify- that renumhering is ‘to -start at a given line. You must 
also specify the nen number for this line (which must be egual to or 
greater -than the cld line number) and the increment. For example, if' 
•you wa.nt to start renumbering at line- 42, and the new line number is to 
•be 4’5 and the increment is to be 5., enter: 

renum 45 5 42; 

If you use the SEKUM subcommand to renumber your data unit, the renumber 
increment you specify is used when you enter the INPUT subcommand the 

next time during the EDIT session. For example, if the following 

■ sequence, occurred: ' • • 

11 st; 

OOOTO LINE 1 OF EATA UNIT 

00020 IINE 2 OF DATA UNIT 

00 030 LINE 3 OF EAT A UNIT 

END OF DATA 
renum 33; 
input; 

INPUT 

00012 line 4 of data unit 

00015 line 5 of data unit 

00 018 - ; (null line) 

EDIT 

Tour data ■ unit would look like this: 

00003- LINE 1 OF EATA DNIT 

00006 riHE 2 OF EATA UNIT 

00009 LINE 3 OF DATA DNiT 

00012 LINE 4 OF DATA DNIT 

00 015 LINE 5 OF EATA UNIT 

If you mant to override the existing line number increment use the 
increment operand -on the' INPUT subcomraand. 
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4,7. LISTING THE CONTENTS OT A LATA HNII 


The LIST siifacommand allows you to display the contests of a data unit. 

To list -the entire contents of the data unit,, enter: 

list; 

To list a group of lines, enter tie number of the first and last lines 
of the group. For example, to list lines 60 through 140 of the data 
unit, enter: 

list 60 140; . 

You can also use the current line pointer and the rumber of lines to be 
listed. For example, to list the 10 lines that begin with the line 
indicated' by the pointer enter: 

list * 10; , ■ 

To list only one line, indicate the line mi'mber or the' current line 
pointer, .For example, if you wish to list line 72, enter: 

list 72.; 

If you want to list tie line pointed at by the current line pointer, 
enter: . , 

list' * ; 

You- can use the SNUM operand to suppress listing the line numbers. ■ 

list snum; 
list 60 140 snum; 
list * 10 snu'm; 
list 72 snum; 

.. list * snum; 

The LIST subcommand uses a standard listing format. The lines displayed 
will consist of only the data portion of the records. For example,' to 
list a data unit with line numbers suppressed; 

list SNUH; 

LINE 1 OF DATA UNIT 
LINE 2 OF data' DNIT 
LINE 3 OF DATA UNIT 
END OF DATA 
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If you list a data' unit with nuEhers, the system will separate the line . 
number from the data with a blanh. The line number prints- to the left 
of the data. For example, data with a 5-digit line number would printx 

list ; 

ODD 10 LINE 1 OF DATA UNIT 
00020 LINE 2 OF DATA UNIT 
000.30 DINE 3 OF DATA UNIT 


4.8' STORING A DATA UNIT 


The data unit you have created or the changes you made to a previously 
existing data unit are retained by the system only' until you finish 
usin.g the EDIT corama.nd and its subcommands. That is, as soon as you 
notify the system- that you want to use another command and you get a 
READ! message, your newly created data unit, or your ne-w set of changes, 
is discarded. If you want the system to make your new data unit 'a 
permanent data unit, or if yor want the system to incorporate your 
changes into the existing data unit, yen must use the SAVE subcommand of 
the EDIT command. 

For example, in the following sequence you create a data unit named 
NODUEE— CODE and ask the system to store it as a permanent data unit; 


EE ADY 


edit module- 

-code (editor, esvalid) ; 

INPUT 


OOO'IO. 

identification division 

00020 . 

program-id esvalid 

00 030 

environment division 

00040 ; 

(null line) 

EDIT 

• 

sa ve ; 

■ 

EDIT 


end; 

READY 



In the following sequence you add a line’ to the MODULE-CODE data unit 
and ask the system to make it part of the data unit: 

READY • 

edit module-code (editor, esvalid) ; . 

EDIT 

40 remarks 
save; 

EDIT 

end; 
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READY 

In some cases you may want to retain the existing data unit intact and 
have the system make the changes to a data unit that is a copy of the 
original data unit. To do this you must enter a new data unit name fox 
the copy when you enter, the save subccmmand. For example, if you want 
to keep the HODUIE-CODE data unit intact, and you want your changes to 
-be ma-de to a copy of MOEUIE-CODE named *esvalid2’, use the following 
seguencer 

READY 

edit module-code (editor,, esvalid) 

•EDIT 

40' xemarlcs . ' 

save module-code (editor, esvalid2) ; 

EDIT 
' end? 

READY 

Now you have two data units. The one named UODULE-CODE (EDITOR, 

ES.VAXID) looks- like this: 

00010 IDEKTIFICATICN DIVISION 

. 00020 PROGRAH-ID ESVAXID 

■ 00030' ■ ENVIRONMENT DIVISION 

The data unit named HODDXE-CODE (EDITOR^ ESVAXID2) looks like this: 

000.10 IDENTIFICATION DIVISION. 

00-020 . PROGRAM-ID ESVAXID 

00030 ENVIRONMENT DIVISION 

00040 REMARKS 

You can use the SAVE subcommand whenever you are using the EDIT ccmmand. 
For example, you can create a data unit and save it. Then you can start 
making changes to the data unit and once you are satisfied with those 
changes you can save them to make - them part of the data uni-t. For 
example, in the following seg'uence you create a data unit, save' it, find 
a character string, change it, delete lines 160C and 1610, insert a 
line,, renumber the data unit, list it and save it- 
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READY 

edit module-ccde (editor, esvalid) ; 

INPUT 

01580 
01590 
01600 
01610 
01620 ; 

EDIT 

save; 

EDIT - 

top-; 

find coiatnnd-huf f ex ; 

01-590 CALL 'EXTHACTL* USING COHHAND-LENGTH, COKH ND-BUEEEB 

charge * xcamiDrdxccmraand; 

01590 • CALL ’EXTBACTL’ USING CGHHAND-l'ENGTH , COHN AND-EUIIER 

delete 1600 1610;- 
irsert ^ remove data name if mary; 
renum; ■ . 

list; 

01580 tRENOVE -CCHMAND NAKE 

'01590 CALL ’SXTEACTL’ USING COMMAND-LENGTH, CCMMAND-BUEE ER 

01600 ^REMOVE D-ATA NfiME IE MANY 

01610; ■ ■ . 

sa-ve; ■ 

EDIT 

end; 

- READY 


^remove ccmmand name 

call ’extiac-tl’ nsirg command— length, c oinrand-b uff e r 
=^^data name found 

call ’enampars’ using common-contr cl-blcck 
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4.9 EBDI-BG THE IDTT FUBCTIGHS 


Use -the END suhccmmaTid to end the operation of the EDIT command. If you 
have made changes' to your data unit and have not entered the SAVE 
suJjcommand,' the system -Kill ask ‘you if you Mant 1:o save the modified' 
data unit. If so, you can enter the SAVE suh comm and. IE you do not 
¥ant to save the changes, re-enter the END subcommand- 

After you enter the END suicomraand, you receive the READY message. Ycu 
can then enter any command you choose. 


4.10 ERASING A PER KANE NT UATA UNIT 


Use the ERASE ccromand to remove a permanent data unit f rom . a 
documentation unit. Once a data unit has been erased it can no longer 
be retrieved as an old data unit by issuing an E-DIT command. Any 
reference to it v:ill be as a new data unit. 

For example, to erase a data unit named * MOUUiE-CODF ’ and uniguely 
identified by the identifiers (data, management , dwrite) , enter; 

erase module-code (data-roanagement , dwrite), ; 

Other examples are; 

erase autoflow docaid; 

erase user— manual common recipe; 

If the data unit is found, the system will- prompt you to b,e sure that 
you wish to permanently erase the data unit. Four answer is' yes if you 
decide to erase. A typical dialog would be; 

erase system-block-diagram; 

, If you wish, to erase this data unit enter FES. For example: 
yes 

THE DATA UNIT -REQUESTE-D HAS BEEN SUCCESSFUIIF ERASED 
en.d; 

READF 
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Short 

Name 

tT 

T2 

T3 

T4 

T5 

T6 

T7 

T8 
TD . 
T1 0 

Tir 

T12 

TT3 

T14 

T15 


Data 

SISTEE“C?iEVlii7~iixT7~HAx”T07000~XINEs7~7*NORD 
DESCailTION OF THE SISTEM*/; 

SYSTEE-BLCCK-DIAGEAN, GRAPHICS, MAX 25 PAGES, /=5=SYSTBM 
FLOWCHAETSV; 

SUBSYSTEMS, MAX 20 TIMES ID=SDBSYSTEM-NAME; 

SUBSYSTEM-NAME IN T3, TEXT, MAX 30 CHAEACTEBS ; 

SUBSYSTEM- NODDIES IN T3, MAX 500 TIMES ID=MODULE-TITLE; 

MODDIE-TITXE IN T5, TEXT, MAX 30 CHARACTERS; 

HODUXE-CCDE IN T5, SODSCICO,DE=COBGL EL/1 ASSEMEIEE, 

MAX 100 TIMES, /^STRUCTURED PROGRAMMING IS TO BE 
USED IN AXX PROGRAMS*/; 

MODULE-INPUTS IN T5, MAX _X0_TIMES 1D=I-DESC; 

I-NAME IN T8, TEXT, MAX 8 CHARACTERS; 

I-XESCEIPTION IN T8; 

MODUI-E-CUTPUIS IN T5 , MAX 10 TIMES ID=C-HAME; 

0_NAKE IN T 10, TEXT, MAX 8 CHARACTERS; 

O-DESCRIPTION IN TIO, TEXT; 

SUBSYSTEM-ABSTRACT IN T3, TEXT, MIN 3 PAGES; 
MODULE-ABSTRACT IN T5, lEXT, EXACTIY 2 PAGES; 


EIGURE 3 SOURCE TEMPLATE LISTING FROM THE EDITOR 
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T1 

T2 

T3 

T4 
T1 4 
T5 

T6 

T15 

T7 

T8 

T9 

T10 

Til 

T12 

T13 


SYSTEM-OTERVIB-EJ 
SYSTEM- BLOCK-DIAGRAM 
SUBSYSTEMS 


SUBSYSTEM-KAME 
SUBSYSTEM- ABSTRACT 
SUBSYSTEM-MODULES 

MODULE-TITLE 
MODULE-ABSTRACT 
MCDUIE-CODE 
MODULE- INPUTS ' 

T-NAHE 

1-DESCRIPTION- 
MODULE-OUTPUTS 
0— UAME 

G-D'ESCRIPTION 


EIGUPvE 4 BOUND TEMPLATE LISTING B'ROM DEEINE DATA 
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5.0 TEMPLATES’ AND DATA DEFINITIONS 


Templates specify Basic slewents of i,TiioiraatioD reguired to develop, and 
document a' programming project. Tie manager, iy means of a template 
names the data elements to be collected, specifies their characteristics 
and defines their hierarchical relationshi,ps to each other. The data 
characteristics include, a' data element’s type (TEXT, OEAPHICS, 
SODECE'CODE) , its length and the number of times it can be repeated. The 
hierarchical relationship determines where it is placed in a tree 
structure corresponding to the 'template , 


5.1' TYPES OF TEMTLATZS 


There are two types of templates: source templates and bound templates. 
Source templates are in character string form and axe stored in the 
common' template library or in the private template library for the 
documentation 'unit . A bound template is created from a source template. 
It has a ’fixed internal structure which makes possible the storage and 
retrieval of data elements. There is only one bound template for each 
documentation unit. 


5.2 SOURCE TEMPLATES 


A source template consists of a seguence of data definitions. Each data 
definition describes a data element of the documentation unit. The 
source template is entered through the editor in the normal line by line 
fashion. 

The editor handles' the source template just as^ if it were lines oi. text. 
Each line may be changed', listed, deleted, etc. , using the full range of 
editor subcommands. The editor does not interpret the template data 
definitions. Uhen the edit session is finished, the source template is 
saved in the template library of the documentation unit. Many source 
te-mplates can ' be ' stored in the template library. 


5.3 ' TEMPLATE STRUCTURE 


Template data definition language describes data element attributes and 
specifies the hierarchical structure of data elements in a documentation 
unit. In order to specify hierarchy there axe t-wo types of data 
definitions, those which define group levels (hierarchy) and those which 
define data elements. 
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A group level aefinition is one whicA has other definitions subordinate ' 
to it , 

The' data eleiaent definition is one which does not have any other 
definitions subordinate to it. Only data elements definitions will have 
data physically a-ssociated with -them. 

The highest, level in the template is the template itself -and is 
implicitly defined to be level zero. (See Eigure 4 -'Section ‘5.) 

In addition to a .template having hierarchy It may also have depth. The 
depth is achieved by allowing data- definitions to be used multiple 
times. The data defintion can- be replicated; each replication being 
uniquely identified- The number of times a data definition can be 
repeated ca-n be controlled by the template writer. The repetition is 
created -when the actual data is entered and stored. 


5..4 EATA DEEIKITI.CK lANGUAGE 


Templates contain definitions of data elements,- These data definitions 
describe what data is to be entered by system users for project 
development and documentation. The template is normally designed by the 
project manager ox his designate before development begins. The data- 
definition language is used to. write source templates. 

A data definition (a statement in the' data definition language) consists 
of a short and a long name for the definition, a list of attributes 
(repetition factor, units of measure^ data element type) , designation of 
position in a hierarchy and an explanation of the data definition. Each 
data definition in a source template starts with a -short name and ends 
with a semicolon {;). Th-e data definition format -is: 


short-name long-name -[IH f ather-shoxt-hame'] [ data-eleraent-type] 
[' untts-of-measnr e ] [repetiticn-f actor j £/*explanat ion*/] ; 


short-name 

a ’T’ conc.atenated with 
Valid short-names range 
assigned short-name an-d 
• cannot be assigned to a 


a five-digit integer less than 32760. 
fro-m T1 to T3275S., .TO is a system 
always- refers to the. top level. It 
data definition in the template. 
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long-aame ' 

th-e descriptive ’ name of the data definition. It is a character 
string of length 1 to 30. The first character must be 
alphaietic, characters 2-30 may be alphabetic ' characters, 
digits,, dashes or underscores. Short-names .are not valid' 
long— names. 


f a th e r- shor t- n am.e 

the short-^name of the data definition in the template to which 
this data definition, is subordinate (at the next lowest level 
in the hierarchy). If 'lil’-is not specified the- entry is 
assumed to .be on. the main level which is referred to 
by TO. Se-ven levels of sabor dina-t ion are permitted. 


data--eleraent-ty pe 

• ’the type of data element this data definition defines. 

Data-ele-ment-type may be either TEST, GRAPHICS', or SOURCECOIE. 
■ The format for data-element— type is-: 




A-NY 

SOUECECODE = Iang-1 lang-2,... 


GRAPHICS 

where, lan'g-1 lang-2... are separateA by blanks and are chosen 
from COBOL, lOETSM, ASM, PI/1. The -defanlt for 
data- element-type is TEXT. 

unit s— of ^mea sure 

specifies limits on the size of the data element, if. any. 

The format for the units— of— measure is; 


MIN 

•MAX integer 

EXACTLY 

MiO • • ■ 


CHAEACTJEES 
WORDS - 
LINES 
PAGES 


where MAX, MIN, EXACT lY, MAHY (sizetest), and the integer 
(between 1 and 3'2759 "inclusive) limit the size "of the data 
element and CHARACTERS, WOE-BS, LINES, PAGES give the’ 
units-of— measure (textmeasure) . One word is 10 characters, 
one line is 60 characters and one page is 50 lines-. 
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Defaults': 

1. If no uaits- of- measure is given, the default is 
U'ANY CHAEACTEBS. 

2. If the sizetest is giT/en and text-measure is not, the 
default fox textmeasure is CHAEACTBES. 

3. If sizetest is not give-n and textmeasure is given, the 
default for sizetest is EX’AUTI'S. 

The units— of— measure determines the size of the stored data 
element and in no way affects the size or format of any output, 

repetition factor , 

specifies how may times a data element cr group of 
data elements may occur.. The format for the 
repetition-factor is: 


MAX . 

MIN 

EXA'CTIY integer TIKES ID = id-def-name' 

MANY 


where MAX, MIN, EXACTIY, MINY (sizetest) and the integer 
(between 1 and 32759 inclusive) limit the number of times 
a data element cr group of data elements may cccur., 

The id-def-narae is the name (shori or long-) of the data - 
definition whose value uniguely identifies a particular 
occurrence of a data element. TIMES and the ID = phrase 
must always be given in the repetition- factor . 

Defaults: , . ' 

1. If sizetest is given and tie integer is not, the 
■ default is .MANY TIMES. 

2. .If sizetest is not given and the integer is given, 

the default is EXACTLY integer TIMES. 

3. ■ Sizetest MANY overrides any integer given. . 

explanation . 

any description or instruction about the data to- be entered for 
the definition,. Any EBCDIC character string is allowed. 

Data definitions for group -levels may contain only .the short— name, 1-ong- 
name, IN phrase and repetition-factor parts of the generalized data 
definition. Data definitions for- data elements may- contain all parts of 
the generalized data definition. The only. parts which are xeguired for 
a definition are the short— name and the long-naiae; all others will take 
default values. 
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5.5 BOUND TEMPLATES 


Once the manager is satisfied with his data definition {as wxiften in a 
source template) , it can he translated into the hound template for the 
documentation unit. The bound template consists -of a number of internal 
system tables which determine the structure and the attributes of the 
data in the documentation unit. It also contains pointers to maps which* 
tell where data is stored. The operation of producing these tables is 
known, as ’binding the template*. 

The template binding process creates a bound' template from a sonrce 
template. Prior to .binding, no. data elements may be entered into a 
documentation unit. 

Template binding is the main function of the DEFINE DATA command. The 
DEFINE DATA command also provides -access to the- subcommands to make 
additions or corrections to a bound template. After- the user has 
entered the DEFINE DATA command, he' may enter the template manipulating 
subcommands for which he is authorized. 


5.6 BINDING TEMPLATES 


The two subcommands ’ of DEFINE DATA used in binding templates are the 
TEST subcommand and the SAVE subcommand. 


The TEST subcommand performs .what might be called ’trial binding’. The 
format for the TEST subcommand is: 


TEST USING source-template-name.; 


The source- template-name is the name of a source template stored in the 
documentation unit’s private template library. 

In the TEST process, the source, template is read in line by-line from 
the' source template library. Each line is scanned to recognize and 
extract the data definitions. A data definition may continue across 
many lines but always begins with a short-name and ends with a 
semicolon. 

As the data definitions are isolated, each, is checked for proper syntax. 
If syntax errors are found, a message is sent to you. 
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Scanning continues even thongh an error is found so you can Le- notified 
of all syntax errors. If 119 syntax errors are fonno,, the structural 
relationships given in the ’IB* phrases of definitions are checked for 
validity. If a structure error is found the checking of further 
relationships is terminated- If no errors are. found, you -are informed 
the trial binding process was successful. No results from the TEST 
subcommand are saved in the documentation unit. It is designed- for 
’debugging'* the source' temflate. 


The S'AT/E' subcommand of DEFINE DATA creates the hound template. The 
format fox the SAVE subcommand isj 


SAVE .USING source-template-name; 

The source— tempiate-narae. is the name of a source template stored in the 
documentation unit. ' ' . . * 

The SAVE subcommand performs the same operations as the TEST subcommand 
exce.pt that if the syntax and structure are error— free, the SAVE 
subcommand creates the- bound template. 

5.7 CHANGING BCUHD TEHPIATES 


The template writing and binding, procedures are designed to encourage 
you to make most of your changes to the source template before it is 
bound by utilizing the editor. However, additions and changes to the 
bound template are, inevitable. The ADD, CHANGE and DELETE subcommands 
of DEFINE DATA' are used to alter a bound template. 


The ADD subcommand" has the- fcllowi-ng format: 


ADD long— name. [ IN father— short -name ] • data- element- type ] 

[ units-of-measure ] . [ repetition-factor J [ /^explanation*/ ] 


where all the variables listed in lowercase letters are the same as 
those defined in Section- 5.4. . - 

¥hen an ADD operation is performed, a short-name for the new data 
definition is automatically assigned. The bound template is altered to 
reflect the new definition-- 
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The CHANGE suhcommartd is used to change a data definition name, its 
attributes or its place in the hierarchy. The format of the CHANGE 
subcommand is: 


CHANGE ,old-data-def-narae = new=def-nanie, 
[ IN father-short—name ] , 

£ data— element— type 3, 

£ units- of- measure ] , 

[ re petiticn-f actor ] , 
£/^{=explanaticn*/ J 


Certain changes which could cause- ambiguities or wculd necessitate 
chang.es to the data 'base i-tself are prohibited- Eor example a change 
from a repeated group to a nonrepeating group- Suppose the d,ata 
definition fox T17 wa-s originally specified as occuring MANY' TIMES. If 
data exists for any occurrence of T17 then 


CHANGE T17 EXACTLY 1 TIME 


would be prohibited. 

Or a change from a larger size to a smaller size (e.g, from TOO- pages to 
30 characters) would be prohibited because it would necessitate looking 
at the data to' see if it were already larger than 30 characters. 


To delete a data definition in a bound template, use the DELETE 
subcommand of DEEINE DATA. The format of the DELETE subcommand is: 


DELETE data-def-narae -[in fat hex-short-name ] 


If the data, definition to be deleted has other data definitions 
subordinate to it, then all of the subordinate definitions will be 
deleted. (The entire subtree for which data-def-name is the root will 
be deleted.) If the data definition to be deleted or any data 
definitions subordinate to it have data associated with them, the 
deletion is prohibited. 

In this case you must first use the ERASE command tc erase the data 
elements and then return tc DEFINE DATA’S DELETE subcommand to delete 
the data definition. 
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A-fter changes have been roade, the LIST subcommand can be used to get a 
listing of the bound template. The format for the LIST command is; 


LIST TEMPLATE; 


This will give a listing of the bound template for your documentation 
unit with indentation to show levels of subordination. (See EIGUEE 4) 

If you want a listing of the data definition names and their 
associated attributes enter: 


list template attributes-; 


^Eor instance if you entered the above command, the system would 
respond by typing cut: 


TQ0001 S-ISTEM-OVEEVIEW IN TOOOOO, TEXT, MAX 10000 LINES 
etc. 


In addition to the above information you may also recieive a 
listing of 'any explanations. For this inf ormaticn, enter: 

list template' attributes explanation; 


If the, above command was -entered, the system -would type out: 
(EEFER TO FIGURE 3) 


TOO‘00'1 SYSTEH-OVERFIEW in TOOOOO, text, max 10000 IINSS 
/*HORD DESCRIPTION OF TEE SYSTEM=f=/ 

etc. 


To end a DEFINE DATA session, use the END suhcommano. The' format for 
the END subcommand is: 


END; 
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DEEINS NASA-SISTEM USING SPAEE1 , 5SUERCPE RICTPE-C1AS3 IS 5 

/*THIS IS THE HIGHEST lEVEI RECIPE OE A SIT OF RECIPES NECESSARY 
TO PRODUCE A EOCUHENT FROM THE EATA STORED UNDER TEMPLATE NASA 

-SYSTEMV; 

STREAM SPRINTER TO PRINTER; 

/-SET OUTPUT NAME SPRIETER TO POINT TO LOGICAL NAME PRIKTERV; ' 
STREAM SOBJSEl TO EISK1 

/-POINT OBJECT MODULES TO PERMANENT EISA DATA SETVJ 
LITERAL 'DOMONIC’ OUTPUT IS {SPRINTER ,+20) 

/-TITLE TO BE PRINTED 20 LINES DEEP CN A NEN PAGEVl 
UPAS Ml OUTPUT = (,5) 

/*EOUTE THE DATA-EIEMENT &PAEM1 TO THE SAME OUTPUT STREAM AS THE 

PREVIOUS LITIRAI. IIVE BLANK LINES ARE INSERTED BEFORE PRINTINGV; 
END NASA-SYSTIM; 


FIGURE 5 EXAMPLE OF A SIMPLE RECIPE 
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DEEIKE HASa-SISEEM USING SPAEMl , SSUBICDE EiCIPE“CLlSS=7 
, • /*!EHiS IS THE HIGHEST lE'VEL lECIPE OP A SET OP BECIPES NECESSABY'TO 
PRODUCE A DOCUHENT PECK DATA STORED UNDER TEHPXATE-HASA-S‘-YSTEM*/; 
STREAH SPBINTIB TO PRINTER; 

/*SET OUTPUT NAME SPRINTER TO POINT TO LOGICSI NAME PRINTERV; 

STREAM SOB'JSET TO DISK1 

/*POINT OBJECT MODULES TO PERMANENT DISK DATA SET*/; 

LITERAL ’DCMONIC* OUTPUT IS ( $P BINTER 

/*TITLE TO BE PRINTED 20 LINES DEEP ON A NEW PAGE*/; 

SYSTEM-OVERVIEW OUTPUT = (,5) 

/* ROUTE THE DATA- ELEMENT SPARH1 TO THE SAME OUTPUT STREAM AS THE . 
PREVIOUS LITERAL. EIVE BLANK LINES. ARE INSERTED BEFORE PRINTING*/ 
CALL SDBSYSTEE-HA.KDLEE USING EDITOR-SUBS YST EM, CAIl, EDITOR, CALL , 
ESAVE,CALL,EIEPUT ' 

/*GET SO-BRECIPl FOR DCCUMEHTING THE RECIPE*/; 

DEFINE SUB SYSTEM- HANDLER USING SSUBSYS , SVERB 1 ,SMOD1 , &VEHB2 , 

SHOD 2 ,-5 VE EB3 , S M CDS PE CIP E- CL ASS=5 

. /*A RECIPE TO HANDLE DOCUMENTATION OF A SUBSYSTEM*/; 

LITERAL. ’ EDITOR-SUBSYSTEM' OUTPUT IS (SPRINTER ,+0) 

/*PRINT SUESYSTEM-NAKP AT TOP OF PAGE */, 

T12' (ED'ITOR-S.UBSYSTEN) OUTPUT IS (SPRINTER) . 

/*WRITE THE .SUBSYSTEM ABSTRACT*/; 

. /*THE FOLLOWING INSTRUCTIONS ARE PROTOTYPES TO HANDLE 
SUBSYSTEM MODULES*/; 

CALL MODULE-HANDLER USING EDITOR, SPRINTER; 

DEFINE MODULE- HANDLER USING 6PGM1, SOD’tPOT'T EECIPE-CIASS = 3 

/*A RECIPE TO HANDLE INDIVI.DUAL MODULES IN A SUBSYSTEM*/ 
• LITERAL ■ 'EDITOR' -ODTPDT IS (SPRINTER, 3) 

/❖PRINT MODULE NAME AFTER SKIPPING 3 LINES*/; 

' T1.3 (EDITOR) -OUTPUT IS (SPRINTER) 

/*PRINT THE MODULE ABSTRACT*/; 

SCOBTIDY INPUT = T7 (EDITOR) , OUTPUT = (SEDITOE) 

/*INVOKE COBOL TIDY PROG.EAM EOE SOURCE MODULES; TIDIED 
SOURCE SAVED ON TEMPORARY DATA SET*/; 

SCOBCCHT INPUT = ,($EDITOR) , OUTPUT = (SPRINTER., SCBJSET) 

/*IKVCKE COBOL COMPILER; SOURCE INPUT IS FROM PREVIOUS 
DATA SET; PRINTED OUTPUT GOES TO SOUTNAME, OBJECT CODE 
GOES TO SOEJSIT*/;. 

END MODULE-HANDLER; 

END SDBSYSTEM-HANDLEE; 

END' NASA-SYSTEM; 


FIGURE 6 EXAMPLE, OF AN EXPANDED RECIPE W.E3CH WAS INVOKED 

BY THE COMMAND 'GENERATE NA'SA-S>rSTEi3 USING SYSTEM- 
OVERVIEW, CALL;' 
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6.0 BECIP-ES AND DOCUISENT GENEIATIOK 


The vehicle for prodticiiig o.utpat from DOEOEIC is the recipe. Reci-pes 
provide the ' lin'1t hetween raw data stored ir the documentation unit and 
development and documentation aid programs which produce output. 

Examples of docu mentation aids are compilers, linkage editors, text 
formatters, flowcharters and cross reference generators. 

Recipes may be simple or complex. A simple recipe might, he a recipe to 
compile a single pregram and produce .a listing. A complex recipe such 
as one to produce a user’s mannal combines many data units with many 
output producing programs and formats all outputs into a document with 
table of contents, chapters, headings and page numbering. A recipe is a 
combination of data unit names from the documentation unit, names of 
output producing programs and- instructions for processing and formatting 
the overall document. 

The recipe is written, in the recipe language. It is entered into the 
documentation unit through the editor and stored for immediate or future 
use.” all editor facilities can be used to input and update the recipe*. 
Ihe editor treats a recipe as if it were text and does not interpret 
recipe instructions. 


6.. 1 DOCUMENT GENERATION 


The goal of document generation is to make the production of documents 
as easy as possible for you. In order to do -this three entities used in 
document generation must be specified in advance. These are a recipe, a 
documentation or development aid description (docaid) and a logical- 
physical device table {X—F table). All are, part of the documentation 
unit. In addition, another table, the input-output stream table, is 
automatically built during the generation process. This table is not 
retained after document generation. The recipe, docaid, L-P table-, 
input/output stream table are used during the recipe expansion and 
document production process. 

The actual document production is a separate batch job executed 
independently of the system,. The job stream for this batch job is 
created during the recipe expansion process performed under the control 
of DOHONIC. Uhen the job stream has been created by the IBM version of 
DOEONJC, it is written to a HASP internal reader- (For systems without 
HASP, the job stream is written on a disk and an OS reader must be 
started using an operating system command.) 
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6.2. RECIPE EXPARSICK PROCESS 


The recipe expansion process ccmpiles a joh siream (sequence cf job 
control language- statements) which produces a document from a group of 
inputs specified by you. Before explaining the recipe expansion process 
the vaxious inputs are described. 

6.2.1 RECIPE 

A recipe is a sequence of Instructions written in the recipe- language- 
describing how a document is produced. Recipes can be used -as main 
recipes or as subrecipes. Recipes may be defined with parameters. This 
allows the writing of general purpose recipes in which the names of data 
elements -or documentation aids are specified when the recipe is invoked.. 
If a recipe, is -defined with parameters, the corresponding arguments must 
be supplied in the GERERATE command or CALL instruction. Op to fcur 
levels of calls are permitted. 

6.2.2 DOCUMERTAIION AID DESCRIPTIOS 

A documentation aid description (docaid) is similar in many ways to an 
IBM assembly language macro definiticn. It consists of a docaid 
prototype statement and a series of model statements. The prototype • 
s-tateraerit gives the name cf the docaid and its symbclic parameters. The 
model statements model job ccntrcl languag.e (JCX) s-tatements and control 
cards. One or more job steps are generated from the model statements. 

The symbolic parameters of the docaid prototype statement are divid.ed 
into three classes: inputs, outputs and options. The format of the 
docaid prototype statement is: 


Sdocaidname [IRPDT- (i-1, . . . ) ] OUTPUT^ {o-1 , . . .) ] -0'PTI0NS= {p- 

1 ,...)] 


docaidname 

the name by which the documentation aid wdll be referenced.' 

Syntax is the same as for template and recipe na.mes, 

i-1 

a list of input parameters. They correspond to inputs specified 
in the model statements. There are two types.: 

d a t a- un it-n-a ra es 

usually the name of a data element, but could be a template-, 
recipe or docaid (last three treated as text) . A data-unit 
input parameter generates a -DD ^ statement in the jcb 
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stream. This is follo'wed hy the' data retrieved from the 
data hase. 

i~o stream name 

the name of an input data set generated by a previous 
step in- the document producticn. The name must start 
iifith a $ followed by alphabetic character concatenated 
with zero to six more characters.. 

0-1 

a list of i-o stream .names used for output from this documentation 
; aid (may later be. inputs to other doqaids) . They correspond' 
to outputs in the model statements. 

p-1 ' ‘ ' 

a list ox option parameters used as simple replacement parameters 
in the model statements. If a parameter contains mul"feip-le 
items, it must he enclosed in parentheses. The whole character 
string without the parentheses will be used in replacement. 

An input, 'output,, or option parameter is referenced in the docaid model 
statements according to the following convention: 


SXnn 


where 

€ is. reg.uired and marhs this as a replaceable para-meter. 

X is one of the letters' 1,0 c.r P for input, ou-tpu't, option 

respectively. 

,n(n) is a one ox two- digit num-ber uniguely defining the parameter 
within its class. 

The following is a example of a docaid and its expansion during 
recipe generation. The name of the private ’ docaid is COB Ci-CCMPILE . 


//&P1 EXEC COBUC,PAEa='CLIST' 

//SYSLIB DD' DISP=SHE,I)'SE=TBO.NASA.COPYLIB 
//SYSIN DD SI1(SP1) 

//SYSLIU DD SOI (SPI) 


During the execution of the recipe, the i-o name SCBUIIB has been 
streamed to the logical stream mine OEJXIB whose physical entry 
in the 1-P table (see 6.2.3) is »DISP=SH.E,D£N=TSG.N ASA.OE JIIB ' . 
Similarly, SSODBCE has been streamed to SODECLTE whose physical 


Page 58 



DOHOlJrC USER'S GUIDE 

RECIPES' AMD DOCUMEHT GEUEBAIION 


entry is ■' DISP-=SHE,PS D=TSG.. N AS A .SO DECIIB' . The following docaiU 
prototype statement was used in a recipe: 


SCOBOX-CGEPILE INPDT=SOURCE 

. OUTPUT=$OBUXIB OETICNS=EDITOE 


The expansion of the docaid 'COEOX-COEPIXE’ is as follows: 

//■EDITOR EXEC C CBUC, CXTST’ 

//SYSXIB DD DISP=SHE,DSR=TSO.RSSA-CCPYXIB 
//SYSIN DD DISP=SEB,DSR=ISO.NASA- SODECXIB <EDITOE) 

‘ //SISXIN DD DISP=SHB,.DSH=TSO. RASA. OEJXIB (EDITOR) 

Docaid’S are entered using the editor and stored in the library for the 
documentation unit or in the system' command library. 

■6.2.3 XOGICAX, STREA'M-PBYSICAX DEVICE TA-BXE 

The logical stream- physical device table (X-P table) links logical i-o 
streams used, in a recipe to actual physical devices. ‘ The table is 
entered into the recipe library for a documentation unit by a JCX 
programmer using th.e editor. Any number of these tables' may be entered 
into the recipe library, each with a unigue name. The table to be used 
in a r.ecipe expansion is deslg-nated in the GEREBATE command. If none is 
specified, the system X-P table is used. 

Each entry in this table has two parts-:' 1) a logical stream name and 2) 
a JCX phrase defining the physical device. For example a logical stream 
with the name PEIRTER could define a physical device with JCX phrase 
SYSOUT=A. ’The format for table entires is: 


X=logical-stream-name> P=physical-device-JCX-phrase; 


An X-P table -can be listed either in the form it was input by using the 
editor or formatted by using the XIST subcommand of the GERERATE 
command. , . 

The logical stream names are associated with inpu.t and output names used 
in recipe instructions by using a STREAM instruction-. 
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The recipes, docaid'S and the i-P tables a-re all memhexs of the library 
of a documentation unit. They are permanent in nature. They must all 
exist before a GENERATE command is issued. 

In addition a temporary table (input-output stream table) is created 
only for the duration of the recipe expansion. 

6.2.4 INPUT-OUTPUT STREAK TABX'E ■ ' ■ 

This table ‘contains a list of correspondences between input and output 
names used in' recipes and logical stream names in the L-P table. The 
assignment of a input ox output name to a logical stream is done by the 
stream instruction in a recipe. The assignment is only valid for a 
given recipe expansion and document generation. It can be changed 
within the same expansion or from one recipe expansion to another. This 
allows you to direct inputs and outputs to' different devices without 
changing input and output parameters in recipes. 


6.3 . -RECIPE INSTRUCTION- lANGUAGE 


i reci.pe- is composed; of a sequence ,of character strings called 
instructions. These instructions define- the inputs to be' used, where 
the output is to be placed and the documentation aids to ‘be used to 
generate the output. The general format for a recipe instruction is: 


instx.ucticn-name. [operands] [ /ffexpla nation V ]J 


The instruction, na’me is "talen from the set of instruction names PEEINE, 
END, CALL, STSEA.K, SD.OCAID,, IITERAI, IIST or DUNKY. In addition, the 
LITE'RAL instruction may be replaced by using the required literal string 
in quotes while a fully qualified data element name may take the place 
of the IIST instruction. The total length of the instruction- name and 
operand fields may not exceed 9'80 characters after any variable 
parameters have been- replaced with real arguments. The operands are 
determined by the syntax particular to the instruction and the 
explanation field Is any character string. 

6.3.1 DEEINE INSTSUCTICN 

The define instruction names the recipe. It is the first instruction in- 
a recipe and marks the beginning of the recipe. The format for the 
define instruction is: 


DEEINE recipe-name [ U'S ING-Sparm-1 , . . . ] [ EECIPE-Cl ASS = n] 
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[ /^explanation V ]; 

recipe-name 

the name of the recipe being Ue-fined. It can be from 1 to 30 
characters ^alphabetics, digits, dashes, underscores) long and 
must start with an alphabetic character. 

Bp arm— 1 , . . 

a list of parameters replaced by real values’ (arguments) 
when the recipe is called from the library to generate output. 
Parameters are alphanumeric, 1 to 8 characters long and must start 
with an ampersand, 

n • ‘ ‘ 

an integer in the range 0-9 which denotes the class of this recipe. 
This field is compared to a user’s recipe' authcrizati on for 
permission to use this "recipe. " Class 0 is for the simplest 
recipe's while class 9 is for the most complex. Recipes with a 
class of 7 or higher may only be generated using the batch version 
. of DOMONIC. If the RECIPE-CIASS phrase is omitted from the 
define instruction, a class -value of 9 is assumed. 

explanation 

a character string explaining the recipe. 


6. 3. 2 END INSmUCI-ION 


The end instruction marks the end of a'recipe. Each recipe must begin 
with a DEFINE instruction an.d .end with an END instruction. The format 
for the end instruction is: 


END {recipe-name]- [/*explanaticn=*/ ]; 
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recipe- name 

The name of the recipe being defined. It can he from 1 to 30 
characters (alphabetics, digits, dashes, underscores) long and 
must start with an alphabetic character. The use of 'this field is 
optional. However, if it is used the name must match that on the 
■Define instruction for the recipe. 


ex pi anation 

a character string explaining- the tecipe. 


6.. 3.3 .CALI INS-TSUCTICH 


The call instruction is nsed to invoke a recipe from another recipe. 

This' instruction can be thought of as a •subrecipe’ call. Arguments may 
be passed to match the parameters defined for the recipe. The format 
for the call instruction is: 


CAXL recipe-name [OSIHG arg-1,...J J^/^explanation-^/]; 


recip e-name 

a valid recipe name. 


arg-1 . 

• a list of arguments' coxrespcnding. to the parameters defined" for 
the called recipe. Each argument is a character string with 
a maximum length of 510 characters,. If an argument .contains 
a comma, the argument should be enclosed in parentheses^ The 
parent-heses -axe. net- considered a part of the -argument.- 


explanation . 

any character string. 


6.3.4 LITESAl IKSTEDCTICN' 


The- literal instruction is used to insert a literal into the output 
stream (usually the printer) , The format for the literal instruction 
is: 


[IITEBAL] 'literal— stri-ng • 

[OUTPUT^ ([output-name^E /SMp-i}]) ] ' 
[ /*ex planati on*/ J,;’ 
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literal— string 

a character string. Xf a single guote is -desired withi-h'the 
literal string, t>;q quote marks together must be used. 

ontput— nam e 

the name of the output stream to w-hich the literal is to be 
routed. If not given the' I-O NSHE $PBIHTEB is the default. 

skip— n 

an integer s-pecif ying the numher of lines to be skipped from 
the current -position before outputting this line. To start 
a new page and then s]<ip n lines precede the integer with a 
plus sign, e.g.. +10. A value of zero will suppress skipping 
to a new line. The detault is 1 line. 

explanation 

any character string. ^ 


€.3.5 EATA-OKIT IMSTHUCTION 


The data-unit instruction is used to retrieve a data unit and route it 
to a designated output stream ■ (usually the printer^ for inclusion in the 
document^ The format for the d.ata-unit instruction is: 


[XIST ] data-unit-name— 1 , . . , 

'[ 0 UTFDTj== ([ output— name ][, ski p-n £ /^explanation */ ]; 


data— unit-name- 1 

a list of data units to be retrieved and output. If more than 
one data— unit is listed, the data retrieval will be concatenated 
on output. • 

output-name 

the name of the output stream to which the data units are to be 
routed. The I-O HAWE $P11NTES is the default if no output option 
is given. The ou'tput line format will de.pend on the data unit type. 
Elements of type SOOS'CECCDE and docaids will have each line 
expanded to an 80-character card image with daia left justified. 

Eor templates,, recipes and elements of type text and graphics 
the data will be' divided into 132 character printer lines. Each 
line of the data unit will start on a new line. Data unit lines 
longer than 132 characters will h>e continued on subsequent printer 
lines. 
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skip-n ' 

an integer specifying the number of lines to be skipped from the 
current position betore outputting this line. lo start a new 
page and then skip n lines precede the integer with a plus sign, 
e.g. +10. A value of zero will suppress skipping to a new line. 
The default is 1 line. 


ex plana tion 

any 'character string. 


6-3.6 $-DOC'AID IHSTRUCTION 


The JSdoeaid instruction invokes a development or documentation aid. The 
JCL necessary to execute the appropriate docaid program during the 
generation of a document is assembled. The operands of this instruction 
names the inputs, outputs, and options tc be used for this execution of 
the documentation aid program. > The operands are used to replace the 
dummy parameters in the docaid model statements. Eor a further 
discussion of docaids see Section 6.2.2. The format for the ^docaid 
instruction is: 


$docaid-na-me [ INEDT= (i~1, . . . ) ] • 

£ CUTPUT={0-1, . ..) J 

[OPTIONS= {p~1, .. .) 3 t/^i'explanationV}; 


docaid-name 

the name of the docaid in the recipe library. Follows the rules 
for forming template and recipe names. 

i- 1 • ' ■ ■ 

a list of data unit names (usually data element names) ox input 
names which refer to input streams ox temporary data sets. 

• An input name starts with a $ followed by a,n alphabetic character 
follovred hy 0-6 alphabetics and digits.- 

0-1 

a list of output names referring to output streams or temporary 
data sets. The name formation rules are the same as for input 
names. 

"P-1 

a list of options for the documentation aid program. Each option 
can be a. character string up tc 100 characters in length. 
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explanation 

any character string. 


6. .3. 7 STSEAE IHSIEUCIIOH 


Ihe stream instruction assigns input and output names (i— o names); used 
as axguTtteiits in a $docaid, literal ox data- unit instruction to logical 
input-output (i-o)' streams. The logical i-c streams must correspond to 
existing entries in the l-D table. The format for the stream 
instruction is: 

STHEAM i-o— nam.e TO logical— stream- name [/^explanation*/]; 

i-o- name 

an input or an output name used in a Sdocaid, literal or 
d a t a- un i t ■ in s tr u c tl on . 

logical— stream- name 

. the name of a logical i— c stream in the X-D table given in the 
GENERATE command- 

. expla nation 

•any character string. 


6.3,.8 DDH«Y INSTRUCTION 


The dummy instrnction' is an instruction that does nothing. It is a ’nc- 
op. ’ instructicn. It will most commonly be used as an instruction 
generated . as the result of the replacement of a recipe parameter hy the 
argument *DUMEY’ in a recipe call. The dummy format instruction is: 


DU-EHY [any character string-J; 


The dummy instruction is used to vary the documentation aids invoked or 
the output produced by a recipe. For example, suppose- have two 
recipes, RECIPS-1 and- EECIPE-2 and data element SYSTEM- ABSTE-ACT wh’ere 
RECIPE- 1 calls- RECIPE-2. 

DEFINE RECIPE-1 RIC3PE-CLA-SS=1 ; 
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CALL RECIPE- 2 USING. 

CALL RECIPE-2 USING 
END SEC-IPE-1; 

DEFINE RECIPE-2 USING , ,SINS!M RSCIP E-CLASS=2 

/*lis-t out data elements*/; 


SYSTEM-ABSTRACT; 

„,DDMM.Y; 


SINST1 OUTPUI=$PEINTEE 


END SECIPE-2; 

HECIPB-1 calls EECIPE-2 tmce. The first time it lists 

SYSTEM- ABSTRACT , the second time nothing is listed. If the following 

command - is issued; 


GENERATE RECIPE-1 ; 

in the expanded RECIPE- 1,' RlCIPE-2 sxpa_n_ds to a data unit instruction - 
and a dummy instruction': 


SYSTEM- ABSTRACT ‘OUTPUT=$PEINTER 


DUMMY ODTPUT=$PRINTER 


This example of the, dummy instruction also serves an an introduction to 
the subject of recipe ex,pansion. 
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6.4 -DECIPE EXPANSION AND OUTPUI 6ENEBAII0K PROCESS 


Ihe recipe expansion, process starts with a GENERATE command. The 
command names the recipe to he used, supplies recipe arguments and 
identifies the lcg.i-cal stream-physical device table '{I— P table) to route 
outputs generated. 

You first enter a 'GENERATE command. The command is parsed. The recipe 
library is searched for the recipe and X-P table names given. If they 
are found, the L— P table is assembled and both are stored in working' 
storage. The system returns tc you for a subcojnman^d . 

The GENERATE command has -six subcommands. They are SCAN, PBOCE, BUN, 
LIST, RELP, and END. None of these subcommands require operand's, except 
the PROOF subcommand does allo•^^ the use cf an operand ’WITH JCL’. The 
format is the subcommand name fcllo-wed by a semicolon. 

Use the SCAN s'ubcOTmand to do syntax checking of recipes. The SCAN 
starts with the first line-. of the main recipe and precedes through the 
recipe line by line, expanding the recipe calls as it goes. Each line 
is checked for correct syntax. The entire expanded recipe is listed 
back to you with subrecipe calls indented. . For example if you entered 
the command; 

ge-nerate nasa-system using overview-a, sub syste-m- handler i-o-table = 
standard-io-table ; 

The system would then ask you to enter a GENERATE subcommand, in this 
case SCAN. The system -would then give you a printout, of an expanded 
recipe like the one in figure 6 plus any error messages. Soae possible 
error messages would be: - 

ESCIP'E NAME IN DEFINE INSTRUCTION NOT SANE AS IN PREVIOUS CALI. 

ONLY 4 LEVELS OE SUBR ECI-PES - A RE AILCWED.. . ‘ ! 

END INSTRUCTION MISSING. FOR END OE RICIPS. 
etc. 

The PR'OGF subcommand checks the' existence of inputs and docaids and 
prints an abbreviated' listing {preef copy) of data referenced in data 
unit, literal or docaid instructions. . As in SCAN, a syntax check is run 
first. If a syn.tax error is found, the subcommand is changed to SCAN 
and appropriate error messages are printed. In either case, the 
expanded recipe is listed. By using the ’T}ITH JCL' option, you can get 
a. listing of the generated job control- language in addition to data. 

' An example of the PROOF subcommand is-; 

generate cobol-compile using' ( recipe, rg et data) , clis-t ; 
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ENTER GENERATE SUBCCMMAND. 
proof; . 

DE'FXNE" CGBCI-CCM.PILE DSING &NOINAME, SPASM SECIPI-CLASS IS 0 
SCOBCGMP INEUT=CCDE (RECIPi,RGETDATl) ,OPTIOHS=C1IST 

5^7 IIEES ESGM'INPDT DATA-DNIT 1 EOIXO'N,- TEPE IS COBOX. 

000010 IDENTIFICATION DIVISION, 

000020 PSOGEAM-ID. RGETDATA. 

END COBOX-COHEIXE 

An exaiaple of the FBCOF WITH JCX is; 

generate cobol-compil e using ^recipe,rgetdata) ,clist; 

■ENTER GENERATE SUECOHNAND. 
proof with jcl; 

//GENTEST GOB (X-036,HASA, 5, 5GH) , ’ HASCALl GEN DOC’ 

■ /^PASSHORD ASAK74 

/4=CXASS, A - . 

V-SOUTE PRINT PRIRTER3 

DEFINE COBOL-CONPIXE USING SMODNAME^ SPASM SECIPE-CIASS IS 0- 
SCOBCGMP INPUT-CO DE (RECIPE , RGETDATA), , OPTIONS-CLIST 
//CARDFOEM' EXEC PSM-UISTCAHD 

//STEPXIB DD disp=she;dsn=tso.nasa.ioadiib 

//WRITER ID DNIT=SYSXA,DISP=(NEW,P:ASS} , DSN-SS.TEMP A,SPACE= (TRK, 1 0) 
.//SISODT DD SYSODT-A 

//READER DD - ■ - 

567 TWO XIKES FROM INPUT DATA- UNIT 1 FOXXOW, TYPE IS COBOX. 

OOGOrO IDEHTIFICATIO.N DIVISICN. 

000020 PSQGSAM-ID. RGETDATA. 

//COBOL EXEC COBliC, PARH-’CLIST’ 

V/STSLIB DD DISP-SHR, DSN-TSO.NASA.CCPYXIB 
//SYSIN DD DSN=SSTEMPA,DISP={OXD,PAS-S) 

END COBCI-CCMIIXE 

WXen yott are ready to produce the actual document, use the RUN 
subcommand. As in PROOF, if a syntax error is found, the subcommand i 
changed to SCAN. If some other error cccnrs, processing of the recipe 
is halted and an error message is printed. 

For example; 

generate cobol-compile using { recipe, rg et data) ,clist; 

generate cobol—compile using (recipe ,rgetdata) ,clist; 

ENTER GENERATE SUBCCMMAND. 
run; 
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For a formatted listing, of the I-P tatle named in the GENEEATF command, 
use the IIST suhcommand. The GEHiaaTF session may be terminated by the 
subcommand END. 

an example of the use of the LIST subcommand is: 


generate compile-and-list; 
ENTER GENERATE- SUBCOMHAND. 


lis 

t; 

506 

lOGICAX NAM 

507 

PRINTER 

507 

PUNCH 

507 

OBJ1IB1 

507 

SOURCLIB 

507 

SAYFIIE 

507 

DUHPTA'PE 


PHYSICAI DE¥XCE. 

S¥SODT=A 

SYSOUT={E, ,508 117 16) 
DISP=SH'R,DSH=ISO.'ljASfl.OBJXIB 
D-ISP=SHE,DSN='I SO.HASA.SOUE’CLIB 
UNIT=SYSEA,DSH=SSTEHPFI11 ,DISP= (.NEIU,PASS 
) , SPSCE= (T.RK, 10). 

D KIT=TAPE9, V0X=SEa=N'ASATP VDiSP= (NEW , KEEP 
) ,IAEEL= (,Nl) 
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7.0 INITI&TIHG A PRCJECT 


Th« . SiST'SE’i command allows yon tc use SYSTEM su'tcomman ds. . These 
subcommands axe used by the systems analyst to maintain the system and 
modify critical system tables. Since SYSTEM subcommands are not for use 
by general users, access to this command is restricted. In order to 
execute the SYSTEM command,, a special documentation unit identifier and 
password must be used at SIGMON, ■ . • 

In general., the SYSTEE subcommands are designed to make a docu menta ticn 
unit known to. the system and to manipulate -the data sets, that will be 
used as- the permanent storage for the documentation units. If a 
documentation unit is initiated using common data sets, private data 
• sets can not be allccgted at a latex time, 

A data set is a physical group of records on a disk that has been 
allocated and named. All data sets whose names are used in a~ny .of the 
subcommands must be online, properly initialize-d and available to the 
. system. 

. To initiate a .new documentation unit, use the INITIATE, suhccmmand. 

To allocate a new, private data set tc an existing documentation unit 
that was originally Initiat.e.d using private data sets', use the ALIOCATE 
subcommand. • ' ■ ■ - ' 

To deallocate a .data set from an existing documentation unit, use the 
DEALLOCATE sutcommand. 

To attach common data sets to the- system,, use the ATTACH subcommand. 

To remove a' common data set from the system,' use the DETACH subcommand. 
If the system determines a docuraentcition unit currently has storage 
allocated to it on the data set, the data set will not be detached. 

Eor information on commands and command syntax, see the D0M.CHIC COHHAN'D 
SEEESENCE MANDAL. ' • - , 
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8.0 ENTERING AND CHANGING SECUBIIT CONTHOIS 

SECU.RIIY is a subsystem of DCHCNIC. This subsystem protects the 
documentation syste.m from access by unauthorized users. 


8.1 TYPES Of SECURITY 


There are three' types of security - provided in the system'. They are: 
password security,, functions security and data security. 

Password security controls which users may SIGNON to documentation ■ 
projects. You must be assigned a password and a user identification 
(,user-idj . The passvjord specifies which functions and users are 
authorized for a given d.ocu mentation unit. The user-id is associated 
with a user description record ■which contains the name, address, 
department and passwords. , The manager must enter the user id's and 
passwords before ethers are permitted access to the documentation unit. 
The password, user id, and DUI must be given 'when signing on to the 
system. {DUI is an abbreviation fer documentation- unit— id. it is the 
name by which a documentation unit is knci'fn to the system.) 

Punction -security controls which commands, s.-.g. DEP2.NE DATA, EDIT, 
GENERATE, you may perform- for a particular documentation project. The 
functions authorized are associated with each password. 

NOTE; the executive functions (commands) and their abbreviations 


are: 

SECURITY C 
MONITOR M 
EDIT E 
GENERATE G 
DEEINE D 
ERASE R 
HELP H 


Data security controls which data units you may access or update. The 
data access authorizations are in effect when performing the EDIT or 
GENERATE functions. The authorizations are: 


READ-ONLY you may -only display a data 

unit. 

NRITE-ONIY you may only enter a data 

unit. 

UPDATE you may display, enter and change a 
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da-ta unit. 


COEMBNT7ONXI — you may display, enter and change 

only the comments in data units of type 
-SOUBCECOBE. 


NO-ACC ESS- 


-you may not have access to this data unit. 



NOTE: the abbre viati'ons 

for the 

authorizations are: 


read-only 

read 

X 



write-cjily 

write 

w 



comment-only 

comment 

c 



update 


u 



no access 


n 


8. '2 

SECUEITi RECORDS 




There' 

axe four types of 

securi t-y 

records: 

Password, User, Data 

and Data Exception, 





A password record contain-s the your password, a -list of the functions 
for'wh.ich you ".are authorized, a supervisor's password to which you are 
responsible, user identifier, monitor class and recipe class. 

NOTE; each user password is responsible to a supervisor password and 
higher passwords. This forms various levels of responsibility known 
collectively as the 'pas-sword tree'. A password '-'s .supervisor may 
also be called his ancestor. The supervisor password is entered in 
the 'REPORTS TO' clause. A password -may ha-ve no greater authority 
than his ancestor. 

User records contain, a user identifier,, user name, address, department, 
■password (s) and city. The data in the user record is used for display 
purposes and not for checking. 

A data default record specifies the default data security authorizations 
for a documentation unit. It contains data-type -‘authorization pairs, 
one pair for each of the- following: TEMPLATE, RECIPE, DOCAID, TEXT, 
GRAPHIC'S, and SOURCECODE. 

Data exception records specify exceptions to the data' default 
authorizations for ,a particular data item and a particular password. 

They are composed of a password, user identifier and authorizations 
{read-only, write-only, update and comment-ronly) . 
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8.3 SECURITY COWHAND- 


The SECURITY command, is used iy i:h.e project manager to add, change, 
delete and list all ox parts of the password, user, aata default or data 
exception records. A session to create or charge these recoras is ‘ 
started by entering; 

security; 

The su-bcommands of the SECURITY command are; ADD PASSWORD, CHANGE 
PASSWORD, DELETE PASSWORD, LIST PASSWORD, ADD USEE, CHANG I USER, DELETE 
USER, LIST USER, ADD EXCEPTICN, CHANGE EXCEPTION, DELETE EXCEPTION, LIST 
EXCEPTION, CHANGE DEE AULT, LIST DEE AULT and E-ND- 


8.4 CREATING A PASSWORD RECORD 


A pass'woxd is a unigue set of characters you must supply to meet 
security requirements before gaining access to data. All passwords. used 
in DOWONIC are from 1 to 8 characters. ■ - ' 

When a new pass-word is’ formulated,- it must be added to the password 
file. The password file contains the ccbtrol information necessary to 
-provide password security and, functicn authoriza-tion. 

The newly created password is referred to as a password record, and in 
addition to the password it -will contain the name's of the users who are 
authorized to use that password, the person or position to whcra the 
users or password is responsible, the racnitcr class, recipe class and 
authorization. The monitor class specifies which mcnitcr features you 
may perform. 

A number of monitor features are. possible in DOHONI'C... For Example: 

1. ability for manager to control na.m-es, types, length and 
occurrences of data elements. 

2. password control of allowable functions. 

3. control of data access. 

Each- monitor feature is classified from 1-9 according to its- scope and 
function; In the password record the monitor class refers to the 
highest level of monitoring which you perform/- Monitor class zero means 
no monitoring allowed. It is the same as, not' being authorized for the 
MONITOR command. 
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The recipe class in the password record indicates the highest level of 
recipe which you may execute. Recipe class zero means no recipes may he 
used. It is the same as not being authorized for the GENERJiTE command. 
The purpose of the recipe class is to ccntrol the guality and cost of 
output production. 

You are assigned specific functions which you may perform, e.g. DEEINE 
DATA, EDIT, GENERATE, etc. The functions authorized are associated with 
each password- In the password record, the authorization simply 
specifies which functions are authorized for that password. 

If you want to add a record to the password file use the ADD PASSiOED 
subcommand, 

Eqr example suppose you wanted to- create a password record named 
*TEAM1', You have the following information: users are JOE, DAN, and 

MIKE; supervisor is MANAGES; incnitor class is 2; and authorization is 
BLEINE and MONITOR-., Then jou would enter: 

add- password teami, users = (joe, mike, dan), reports to 

manager, monitor = 2, authorized for (define., monitor) ; 

N'OtE; Users must be already be in the user file. 

If you want to change a field in the record you just created, you would 
use the CHANGE RASSNORD suhccmmand. 

Tor example, in the password record •lEAHl *'if you wanted to add -J'OHN as. 
a user and GENERATE as an authorization, you. would enter; 

change password, user = joh'n, authorized fox generate; 

After you have created a password record, you may want to d'elefe the 
entire record or part of it. , To do this, you would use the DELETE 
P'ASSHORD subcommand. 

Tor example, if yon wanted to delete password record ’TEAMT, you would 
enter; 

delete- password teami; 

The system will respond by asking whether you want the entire password, 
record "deleted. If so, you would enter: 

yes; 

If you only wanted to delete J"OHN as a user in the password record 
•TEAMI’, you would enter: 
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delete password teaml, user = John; 

If at any time you would like a listing of the password record, use the 
LIST PASSWORD subcommand. 

For example, if you want a listing of the password record 'TEAHV you 
would enter: 

list password teami; 

8.5 CREATING A USER RECGID- 


You may add a record to the user file by using the ADD USER subcommand. 

For example, if you- wanted to create a user record and you haTre the 
following information: u.ser— id is EANAGER 5 . name is SMITH; city is 
DALLAS; and department is DPC; ycu w-ould - enter: • ^ ' 

add user manager,, name = smith, city = dallas, department = dpc; 

NOTE: Passwords are auto maticllay updated when users are added 

or' deleted from the password file. Therefore, a user must be 
in the user file before he can be added to a password. 

If you want to chang.e a record in the user file, use the CHANGE USER 
subcommand. ' • • 

For example, if the user record is EANAGER, the street is MA.INDRAG and 
the CITY is SNYDER, you would enter: 

change user manager, street = maindrag, city = snyder; 

To delete a -user record or part of it use the DELETE USER subcommand. 

For example, if you want to delete the' user record MA.NAGER, you would 
enter: 

delete user manager; 

Use the LIST USEE subcommand when, you want a list of user records. The 
record may be'listed with or without passwsords. . Howe.ver, only the 
master password may use the list password feature. ■ 

For example, if you want to list an entire record named MANAGER, you 
would enter: 

list user manager-; 
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To I±s,t "the passwords within the record NA-NAGEE, you would enter: 
list user manag.er, password; 

To list, all the users and tter.e password enter: 
list user manager password all; 


8.7 CREATING AN EXCEPTICN FECOBD 


An entry may be added to an exceptions file by using the ADD EXCEPTION 
subcommand. Eor exa'inple if you wanted to add two exceptions to record 
SECUEI TY. DATA and password TEAN2 has authorization CONNent, password 
TEAH3 has authorization E.EAD-ONLI and the CHG- APPROVAL is YES, then you 
would en-tsr: 

add exception security .data, password team2, authorization 
comiaent, password team3, authorization read-only, 
chg^appro'-val yes; . 

NOTE: You jaay add, change, delete ox list any passwords in 

the records in which you have control . 

In order to change an entry in the exception file-,, you use the change 
exception subcommand. For example if you want to change an 
authorization from READ-ONLY to UPDATE and one exception of record 
SECURITY. DATA is password TEAH3, then enter: 

change exception security .data password teamS authorized 
for update; 

Use the LIST EXCEPTION subccmmand to get a listing -of an exception file 
or its subfield. Por example if you want to list the exceptions for the 
data, unit SECURITY. DATA, you would enter: 

list exception security. data; 

NOTE: You would only reeceive the authorizations for your 

password and the change approval. 

If the passwords are known for the data unit above they may also be 
entered. For example: 

list exception security. daf a, passwords = team3, team2, teami; 
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To -list' the exception change-approval for SECDBITI-. DATA, enter: 

list exception security. 3ata chg-^approval; 

To "delete a subentry- in an exception file use the DELETE EXCEPTION 
.subcommand. If you simply enter the command DEXETE EXCEPTICN without 
specifying any subentries, you will receive a message asking is you want 
to delete the entire record. ' You may at that time enter YES, in which 
case the file will he deleted or NO in which case you may then specify 
•which subentries you want deleted. 


8.7 CEE.ATING A DEE AULT RECCED 


The only two commands a'vaila.ble to you in the area of the default file 
is the CHANGE DEPADLT subccmmand ox the LIST DEEADLI subcommand. 

Use the CHANGE DEE AULT subcommand to change the authorization in 'the 
default file,. Eor example if the recipe is READ-ONLY and the text is 
COMMENT— ONLY and you want to change bcth to ’.UPDATE , enter: 

cha-n'ge default recipe = update, text = update; 

The LIST DEE A.UIT subcommand give you a listing of the default file. To 
receive a listing,, you would enter: 
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lElETYPE NODE! 33 I-EHMINAI-S 


Keyboards 

Heietype Model 33 terminals Ija'ue a four row typewriter- like keyboard 
which can generate 96 coSes out of a full 128 character ASCII set. 

Printer: 

Teletype Model 33 printers can print 63 chaiacters, including 
. uppercase' alphabetics, numerics, special synbcls and punctuation 
marks. The 40 0 foot rclls of paper axe friction— fed ; pin-fed 
is optional. Pages 8.5 inches wide are accepted by friction-fed. 

Printing is at 10 characters per inch with vertical spacing at . 

6 lines per inch. Automatic double spacing can be utili'zed. 


TELETYPE MODEL 35- TEE 'MIKA LS 


Keyboard; 

Teletype Model 35 terminals have a four row typewriter-like 
keyboard which can generate 96 characters out of the full 128 
character ASCII set. By depressing corabinaticns of keys, 
control codes are generated. 

Printer; ‘ • - . ■ ' 

Teletype Model 35 printers accept friction-fed forms, from an 
8.5 inch wide, 400 foot roll. 'Vertical spacing is at 6 lines 
per inch with automatic double spacing 'possible. Eoxizontal 
spacing is 10 characters per inch. Automatic double spacing 
is possible. 

A total of 63 characters can be printed including numerics, 
uppercase alphabetics and special symbols. Terms up to 9.5 
inches wide hare an option of a pin-feed mechanism.. 
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lEiETYPE aODEL 37 TEEHIMIIS 


Keyboard: 

Model 37 teriDinals have a four row typesriter 
arrangement. The heyloard can generate 128 graphics and control 
codes of the ASCII character set. To generate the full range, 
shift keys, control and prefix are used in conjunction with 
character keys. Any character can he repeated automatically 
by depressing the key below the ncrmal depressed position. 

Printer: 

Teletype Model 37 printers can print 94 ■ (standard.) , 110 or 
12 6 symbols of the ASCII graphic set. The hori. 2 ontal pitch is 
10 characters per inch with a future option of 12 characters, 
per inch. Vertical spacing is 6 lines per inch and op.erators 
can choose double spacing. 

Standard platen is 8.5 inches wide with friction— feed . Pin— fed 
platen -at 9.5 inches wide is optional. Options to be announced 
are platens designed to accomracdate forms 3. 625 to 9'. 5 inches 
• wide, edge to. edge. Bear leading is standard, while front loading 
is optional. Continous forms may be accommodated and stacked in 
the rear. . - . , . ‘ 


TEXETYPE MODEL 38 TEEMIHAIS 


Keyboard: 

Teletype Model 38 terminals have a four row typewriter 
arrangement. Ccntrcl codes of ASCII character set and all 128 
graphics can be generated fretn the keyboard. To generate the 
full range, control, shift keys and escape are* used in conjunction 
with character keys. Characters can be repeated by automatically 
depressing the key below the normal- depressed position. 

Printer: . . 

Teletype M.odel 38 printers can print 94 symbols of the ASCII ■ 
graphic set in addition to upper and lowercase alphabetics and 
up to 132 characters per line. Horizontal pitch is 10 characters 
per inch. Vertical spacing is 6 lines per inch and operators - 
can choose double spacing. With pin-^feed, standard platen 
is. 15 inches .wide. An option accommodates friction-feed 8.5 
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inch roll paper anU 14 7/8 inch pin-feed forms. 


IBE 10-50 KATA COfJHUNICflTlCNS SYSTEH 


Printer: 

The 1052 printer-Aeyhoard is hnilt aronnd an IBM Selectric 
typewriter. 

Uhen. incln’ded in th'Q 1050 cysteni/ the 1052' carries system switches 
and indicators.. There are two models which correspond to the two 
communications models of, the 1051 Control Unit. The main 
difference, is the insertion of a different set of switches and 
indicators corresponding to the ccminunications/home-loop 
and communications-on ly modes of operation of the two 1051 
models. ’The printer -portion and the data -'entry portion of the 
keyioard for the twc models is the same. 

Eighty-eight different symbols including upper and lowercase 
aiphahetlcs at 14.8 or' 8.33 characters per second can be 
printed. The- printer provides a 15 inch, friction-fed carriage 
. with a 13 inch writing line (130 characters) is provided- 
Pin-fed platen is optional. 

Vertical spacing is at either 6 or 8 lines'per inch. 'As an 
option, the 1052 can be equipped with a vertical form control 
mechanism to allow autcmatic spacing to predetermined positions ' 
on a form. A. second- option speeds the return of .the typing 
element on a carriage return by about 50 per cent. 


IBM 2741 COMMUNICATICK TEEMINII 


Keyioard: 

IBM 2741 Communication terminals have a 55 key typewriter style. 
The keyboard can yield any of the 8 8 upper cx- lowercase 
alphabetl.es, numerics and special characters through upper and 
lowercase control codes. Three "keyboard's are available and 
each corresponds to one of three transmission codes. 

■ The Typamatic Key option gives a repeat action while the 
hyphen/underscore, backspace and space-bar keys -are held 
depressed. 
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Printer: 

IBH 2741 Communication printers print data from the communication 
facility or input from the keyboard.. 

The rated print speed is 14.8 characters per second and print 
symbols total 88. 

■ Several interchangeable print elements are available for each 
code. The PTTC/EBCJ) and PTTC/BCD -codes are compatible except 
for punctuation and special symbcls, IBM stresses the use of 
identical keyboards and print elements based on the selected 
■ code for all terminals within the same network- 

Priction-fed or pin-f.ed {optional) fanfold' forms up to 15.5 
inches wide are acccm mod-ated by the printer. The- writing 
width is 13 inches. 

Horizontal spacing can be either 10 or '12 characters per inch. 
Vertical spacing is 6' or 8 {optional) lines per inch. 

IBM stresses the avoidance ox intermixing character spacing on 
terminals within the network. 


Page 81 



D0J30NIC USEE’S GUIDE 
IPPENDIX B 


SSEPLE EM-CH JOB DECK 


//JOBiJAME {accoxint information.) 

//STEP 'exec ‘ DCMODIC 

//SYSIK DD D ATa,DCB=ELKSIZE=80 


(batch input to system) 


Explanation: 

The system is invoked by the execution of a procedure stored 
in the system procedure library. In the above example this 
procedure is given the name lOMOWIC. The SYSIE card identifie 
the batch input to the system. It is in 80 character card 
format and must start -with a SIGMON command (see format in 
DOMONIC COHMAND EEEESENCE HANDAL.) 

C013HAND ’GENERATE NASA-SYSTEM USING S YSTEM-CVEHVIEW,CAIL; ' 
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1.0 INTRO DUCT lOB 


DOHONIC is desicnefl to document any computer language and run on any 
hardware while tahing advantage of existing documentation aids. The 
system currently supports EOETEAR, COEOl, ASM and PL/1. DOMONIC is the 
first system that brings all types of documentation aids together under 
a single system. 

Program documentation consists of all those items which are formulated 
to aid someone in understanding a program, but which are not a required 
part of the program. 

DOaONIC is written in A NS COBOL and implemented on IBM/360. The system 
can be operated in either batch (card input, line printer output) mode 
or interactively through typewriter-type terminals (IBM 2741, 1052 and 
TNX) . 

You can communicate with the system by entering reguests for work 
{commands) on a terminal or punched cards. The system will then respond 
to your requests by performing work and sending messages to you. 

The command establishes the scope of the' work to the system. The scope 
of some commands* work covers many operations that are identified 
separately. Upon entering the commands, you may specify one of the 
separately described operations by typing a subcommand, A subcommand is 
also a request for work; however, the request for work is a specific 
operation within the scope of work created by a command. 

The DOHONIC command language is composed of commands and subcommands. 

The commands and subcommands are verbs that describe the work to be 
done. The data that you must provide is defined by operands. Operands 
are words or numbers that accompany the command names and subcommand 
names. If you choose to omit the operand from the command or 
subcommand, most of the operands have default values that will be used, 

ALL COMMANDS AND SUBCOMMANDS MUST EE EOLLOWED BY A SEMICOLON.- The 
semicolon marks the end of the ccmmanfl or subcommand. 

This reference manual defines what each command can do and how to enter, 
or type in, a command at your terminal or on punched cards.- 
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2.0 INPOBMATIGN NEEDED IN CODING COMMANDS 


To use the DOMONIC command language you should know: 

* The syntax of a command. 

* The way to enter a command. • 

* The data unit naming conventions. 

You should also he aware of the aids available to you: 

* The HELP command. 

* The messages sent hy the system to you. 

2.1 COMMAND SYNTAX 

A command consists of a command name which is usually followed hy one or 
more operands. The command name is usually a verb that describes the 
function of the command. For example, the SIGNON command connects the 
user to the system. Operands supply the specific information needed for 
the command to carry out the requested operation. For example, operands 
for the SIGNON command identify the user signing on, the password being 
used and the name of the documentation unit to he accessed: 

SIGNON USER ARSEVEK PASSNOSD R7 DUI NASADOC; 

command operand operand operand 

(user-id) (password) (documcntation-unit-id) 

There are two types of operands that are used with the commands: 
positional and keyword. Positional operands follow the command name and 
precede keywords. 


2.1.1 POSITIONAL OPERANDS 


Values that follow the command name in a prescribed sequence are called 
positional operands. The values may be one or more symbols, names, or 
integers. Positional operands are shown in lower case characters in the 
command descriptions of this manual,' A common positional operand is: 

data-unit-name 

You must substitute > data-unit-name* with an actual data-unit-name when 
you enter the command. 
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2.1.2 KEYNOBD OPEHANDS 


Keywords are specific names or symbols that have a particular meaning to 
the system. Keywords may be included in any order following the 
positional operands. In this reference manual, J^eywords are shown in 
upper case characters. A common keyword is; 

MONITOR CLASS 

In some cases you may specify values with a keyword. If the keyword has 
multiple values, the list is enclosed within parentheses and the values 
are separated by commas: 

PASSWOBD £=] (password,..,) 


2.1.3 DEilMITEES 


You should separate the command name from the first operand by one or 
more blanks when you type a command. Separate operands by one or more 
blank's or a comma. Eor example: 

edit nasa-module-1, 
data- element-type , 
units— of-measure, 
repetiti on- factor; 

For an on-line system, enter a blank by pressing the space bar. 

For the batch system, leave one or more columns blank. 

The system will stop scanning for operands after you type a semicolon 
at the end of a ccmmand. 


2.1,4 SYNTAX KOTATICN CONVENTIONS 


The notations describing command syntax and format in this manual are 
defined in the following articles.- 

1, The symbols below are used to define the format, (Never type 
them in the actual statement.) 
hyphen - 

underscore _ 

braces | } 

brackets [ ] 

ellipsis ... 

NOTE: A hypen and or underscore may be used in an actual 
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data ’Unit name. 

The special uses of the above symbols are explained in 
articles 5-3. 

2- Type uppercase letters and wotds, number, and the symbols 
listed below in an actual ccmmand exactly as shown in the 
statement definition. 


apostrophe * 

asterisk ^ 

comma , 

egual sign = 

parenthesis {) 

period 

semicolon ; 


NOTE: IS and SEE may be used in place of =. 

3. Lowercase letters, words, and symbols appearing in a command 
definition represent variables for which you should replace 
specific information in the actual command. 

Example: if * user-id* appears in a command definition, 

you should substitute a specific value (for instance, flRSEVEN) 

for the variable when you enter the command. 

4. Stacked items represent alternatives. You should choose only 
• one such alternative. 

Example: The representation 

data- element 

template 

recipe 

indicates that either data-element or template or recipe is 
to be chosen. 

5. Hyphens join lowercase letters, words, and symbols to make 
a single variable. 

6. An underscore specifies a default option- If you choose an 
underscored alternative, you do not have to type it when 
you enter the command. 

Example: The representation 

aata-elemen t 

template 

recipe 
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indicates that you are to choose either data-eleraeut or 
template or recipe; however, if you choose data-element, 
you need not type it, because it is the default option. 

7, Braces group related items, such as alternatives. 

Example: The representation 

DGCDMENTATIOH UNIT £“=3 document at ion-unit- id 
DUI 

indicates that you are to select either documentation unit 
or dui. If you choose dui, the result is: 

DOI = DGCOMENTATION-UNIT-ID 

8, Brackets also group related items; however, everything 
within the brackets is opticnal and may be left out. 

Example: The representation 

SOURCECODE 

TEXT 

GRAPHICS 

indicates you may select one of the items enclosed within 
the brackets or that you may leave out all of the items within 
the brackets 

9, . An ellipsis indicates the preceding item or, group of items 

can be repeated more* than once in succession. 

Example: 

(f un.ction-1, . , .) 

indicates that function- 1 can appear alone on can be 
•followed by function-2 any number of times in succession. ‘ 


2.1.5 . SUBCOMMANDS 


Uork performed by some of the ccramands is divided into individual 
operations. Each' operation is defined and requested by a subcommand. 
To request one of the individual operation, you must first enter the 
command. Then you can enter a subcommand to indicate the particular 
operation that you want performed, You can continue entering 
subcommands, until you enter the END subcommand. 

The commands that have subcommands are DEFINE DATA, EDIT, GENERATE, 
SYSTEM, MONITOR, and SECURITY. Nhen you enter the DEFINE DATA command 
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you can then enter the subcommands for DEFINE DAIA. Likewise, when you 
enter the EDIT, GENERATE, SY-STEN, HGNITOE and SECURITY commands you can 
enter the appropriate subcommands. 

The subcommand syntax is the same as that of a command. A subcommand 
consists of a subcommand name followed, usually, by one or more 
operands. The discussion of operands and delimiters apply to 
subcommands as well as commands. 


2.2 HOW TO ENTER A COMMAND IN INTERACTIVE NODE 


A terminal session is designed to be a relatively simple process: you 

identify yourself to the system by entering the SIGNON command and then 
reguest work from the system by entering other commands. To enter a 
command or subcommand: 

1. Type the command or subcommand name and any operands that 
you choose followed by a semicolon. 

2. Press the carriage return key. 

You may begin typing af any position on the line; you don*t have to 
begin at the lefthand rargin. You can type command names and operands 
in either uppercase or lowercase characters. You may prefer to type 
your input in lowercase characters so that you can distinguish your 
input from the system’s messages on your listing. The system prints in 
uppercase characters - 

In order to delete a character use the BACKSPACE key. Every backspace 
deletes one character. 


.2.3 HOW TO ENTER A COMMAND IN EATCH MODE 


When using DOMONIC in a card-oriented environment, all commands and data 
to be entered into the DOMONIC system during a session must be prepared 
prior to using the system. The cards would normally be prepared with 
some off-line key-entry system such as a keypunch. After the cards have 
been prepared and checked for accuracy, they can be run as data cards in 
a batch job deck. A batch job deck begins with a job card to identify 
the user, how long the job may take to execute and ether administrative 
information. Besides being a job control language card, the job card 
must conform to the installation’s format. The next cards are also JCI 
cards. These cards will begin the execution of the system* for IBM 
installations the JCl will consist of one ’EXEC’ card which enters the 
catalogued procedure name that is necessary to invoke the system 
followed by one ’//SYS IN DD *’ card. 
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The DOHONIC command and data cards a-re placed next in the deck 
immediately following the * //SI SIN DD ** card. These cards are read one 
at a time by the DOMCHIC system jost as if they «ere entered from a 
terminal where each card represents one line from a terminal, An end- 
of— job card then terminates the batch job deck. 

There are often slight differences between batch job decks from one 
installation to another. Appendix B shows a sample batch job deck and 
explains what information is reguired for a typical installation. The 
example given should be adapted to the conventions and procedures for 
your installation. Note that the commands and data will not change, 
only the makeup of the rest of the deck may change. 

Certain conventions apply to the use of cards in the DOHONIC system. 

They are: 

1. Each card represents one input line, 

2. Only those characters that can be punched on the 
card can be input. 

3. Since a card— oriented system is not interactive, 
there is no character or line deletion, 

4. All messages sent to you by the system will be 
printed in uppercase letters. Output from 
text-handling applications which have both upper- 
case and lowercase letters will print both 
cases if the proper type line printer is 

is specified in the JCL cards. If not, 
lowercase letters will be printed as the cor- 
responding uppercase letters. 

Bemember that each card entered in seguence, in a card-oriented system 
corresponds to each line entered, in seguence, in a terminal-oriented 
system. Since all examples in this manual assume an IBM 2741 
Communications Terminal, it is only necessary to notice the order in 
which information is reguired to be entered in order to prepare a 
corresponding card deck. 

If the information being entered does not fit on one card, simply 
continue it on the next card. After jou have entered all the 
information for that command, type a semicolon (;) . The semicolon 
convention must be observed even if the command you are inputting fits 
on one card- The semicolon is used by the system to delimit the end of 
a command. 
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2.4 DATA-ONIT NAMING CONVENTIONS 


The jaame give a data unit should follow certain conventions. A data 
unit name can either be a template name, recipe name, docaid name or 
data element name. 

A template, recipe and docaid name all have a maximum length of 30 
characters. The first letter must be an alphabetic character while 
positions 2—30 of a name may contain alphabetic characters, digits, 
dashes and underscores. No other characters including blanks are 
pexmissable. An example of a template name is: ' 

SYSTEM-DATA-DEEINITIQN 

NOTE: a template name uniquely defines a template to the system. Within 
a template individual data elements o.f the documentation unit are named 
with a long name. 

An example of a recipe name is; 

N ASA-S YSTEM- RECIPE 

An. example of a docaid name is: 

EL OWCHAETEE 

A data element name consists of both data definition names and 
identifiers. 

NOTE: the rules for writing an ID (identifier) ' are; 

1. An ID has a maximum length of 30 characters. 

2. It must begin with an alphabetic character. 

3. Positions 2-30 may contain only alphabetic characters, dashes# 
digits and underscores. Ho otter characters are permissable. 

The rules for writing data element names are; 

1. A short name must begin with the letter *T' and be followed by an 
integer. T1-T32759 are the only 

acceptable short names. An example of a short name is; 

T13 

2. A long name has a maximum length of 30 characters. It begins 
with an alphabetic character and positions 2-30 may contain only 
alphabetic characters, digits, dashes and underscores. No other 
characters are permissable. T1-T3275S cannot be used as 

long names. They are reserved for short names- 
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SYSTEM- ABSTRACT IN T3 
{loug-name) <sh.oxt-nam€) 


3. A simple data element name is a long name or short name, (See 
rules for writing long or short names). Exarples of a 
simple data element are; 

T5 (short name) 

SYSTEM- ABSTRACT (long name) 

4. To qualify a data element name simply give the names of the levels 
in the template hierarchy. (Figure 5 and 6, Section 10.0.) A 
qualified data element name is: 

HODUIE-TITLE.SDBSYSTEM-MOEDLIS.SUBSYSTEMS 

NOTE: As long as the qualified name is unique, intermediate level 
names do not have to he given. A qualified name must he qualified 
to the level which makes it unique, but an identifier must be given for 
each level with repeated occurrences whether or not the data 
definition name is given for that level. 

When qualifying data element names, the data definition names 
must he separated hy periods and must be listed from the most specific 
to the least specific, (Ercm bottom level upward) For example in, 
Figure 5, if you wanted ’SUBSYSTEM-ABSTRACT*, you would enter: 

SU BS YSTE M-ABSTRAC T. S.OBSY STEMS ; 

or 

You could enter just the short name. For example: 
SUBSYSTEM-ABSTRACT.T3; 
or 

T14.T3; 

or 

Tin. SUBSYSTEMS; 

5. If any ■ sub— level of a qualified name is a repeated occurrence, 
additional identifiers are needed in order for the system to 
locate the desired level. 

‘11 
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An identifier for each level of heirarchy must he given from the 
least specific to the most specific. For example: 

SUBSZSTEfl-NAHE.SDBSYSIEHSj[DAIA-MANAGEJ!lENTrDENEATA) 

cr 

T4.T3 (DATA-KANAGENEN!E,DENDATA) 

If you wanted I-DESCRIPIION {Figure 5) which is located 
on level TIO, you would enter: 

I-DESCETPIICN. aODUXE-INPDlS. SOBSYSTEH-MODaXES.SDBSYSIEHS 
( DAI A-JHANAGEaENT,DFNDAT A, COMMON-AREA) 

or 

II 0.T3. T5. 13 {DAIA-MAHAGEMENI, DF NDATA, COMMON-AREA) 

cr 

Any combination of long or short names: 

I-DESCBIPTI0N(IA1A-HANAGEMENT,DFNDATA, COMMON-AREA) 

110 (DAIA-MANAGEMENT, DENE AlA , CCHHC K-A SEA) 
I-DESCEIP1ION.T5{DA1A-MANAGEHEN1,DFNBA1A,COHMON-ASEA) 
T10.18{DA1A“MANAGEME NT , DFNCAIA, COMMON-AREA) 

Identifiers must be enclosed within parenthesis, separated by commas 
and listed from left to right beginning with the most general to 
most specific. (Begin at the top and work toward the bottom.) 


2,5 SYSTEM PROVIDED AIDS 


Several aids are available for your use: 

1. The HELP command provides you with information regarding 
the commands. 

2. The conversational messages guide you in your work at the 
terminal. 
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2. 5. 1 The HELP Commajid 


The HELP comiaand provides you wi-th iaforraatioB about the function, 
syntax and operands of commands and subcommands. When you 'enter the 
HELP command, the system displays at your terminal a brief description 
of the function you are trying to perform or operand you are trying to 
enter. {If you need help uith the HELP command enter: help help.) 

To receive help «ith the function,, syntax or operands of a command, you 
should enter: 

COMMAND OPERANDS 


HELP [command name] [EDNCTION] [SYNTAX] [OEEEAND] 


command name 

the name of the command uith which you need help. 

P0NCTION 

the function of the command with which you help. 

SYNTAX 

the syntax of the command with which you need help- 
OPERAND 

the operands of the command with which you need help. 

NOTE: if you Just enter the command HELP followed by a semicolon, you 
will get a list of all the commands of the system. 


Example 1 

operation: Asking the system for help. 


he Ip; 


The system will respond by typing cut: 

?ALID~COMMAiDs“‘iii7 siGHON7"~slGioFE7**EDIT7~slc’DiiTy7~HONIToi7~^NiBATE, 
DEFINE, ERASE, HELP, END 
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Example 2 

operation; Same as above. 

known; You have not Y^t signed on, 

help signon function; 


The system will respond by typing ont: 

the" CO mm N D~S I G N 6 h’’ lii TIA Tis~U sl~ 0 E~T BE~S Y STE M 


Example 3 

operation; You need help with fhe SIGNON syntax. 


help signon syntax; 


The system will respond by typing out: 


SIGNON ’DSEB [=] USEB-ID, 

PASSWOBD [=] USEH-PASSNOBD, 

DOCUMENTATION DNIT [ = ] DOCDME-HTATION-UNIT-IDENTIEIEB 
DUI 


Example 4 

operation; You need help witli the operands of SIGNON. 


help signon operands; 


The system will respond by typing out: 

Usii-lil iN~’EIGHT”cHAiACTEi~STBliG~TflAT~DEiTlilES*'THi~DSii7~ 

DSES-PASSNOED; AN EIGHT CHAEACTEB STBING TEAT IDENTIFIES THE 

PASSNOBD THAT THE CSEB IS IDTHOBIZED TO USE. 
DOCUHENTATION-UHIT-IDENTIFIEB; A CHASACTEB STRING (MAX lENGHT 

30 CHARACTERS) THAT IDENTIFIES A DOC DNIT. 
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2.5.2 MESSAGES 


There are four types of messages: 

^Mode Messages 
^•Prompting Messages 
^Broadcast Messages 
^Informational Messages 

*Mode Messages 

A mode message informs you the system is ready to accept a command, 
subcommand or data. When the system is ready, the mode message printed 
at your terminal is: 

READY 

If you enter a command that has subcommands, the system will output a 
mode message that is the name of the current command, such as: 

EDIT 

If the subcommand, you entered expects data to he entered, the system 
will type out the mode message: 

INPUT 

The mode messages are displayed when the mode changes. 

^Prompting Messages 

If you neglected to input some Information or if some information yon 
input was incorrectly specified, the system will type a prompting 
message. Such a message requests you to supply or correct that 
information. The following is an example of a prompting message: 

ENTER SODRCECODE TYPE 

You should respond by entering the requested operand; in this case the 
SOURCECODE-TYPE, and by pressing the RETURN key to enter it. Eor 
example, if the sourcecode-type is GRAPHICS, you would respond to the 
prompting message as follows: 

ENTER SOUECECODE TYPE 
graphics; 
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*Broadcast Messages 

Broadcast messages are messages of general interest to users of the 
system. The system operator can broaicast messages to ali users of the 
system or to any specified ’signed-on* user. Usually these messages 
will concern system availability. For example: 

NASA WILL HALT OPERATIONS EOR P.M. IN 30 MIN. 

*lnf ormational Messages 

Informational messages tell you about the system’s status and your' 
terminal session. For example, an informational message may inform you 
when document generation has ended, or how much time you have used. 
Informational messages do not reguire a response. In some cases, an 
informational message may serve as a mode message; for example, an 
informational message that informs you of the end of a subcommand’s 
operation also implies that you can enter another subcommand. 
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3.0 ' EDIT CoBunand 


The EDIT command Is the primary facility for entering data into the 
system. Therefore, almost every application involves some use of EDIT. 
Elth EDIT and its subcommands, you create, modify, store and retrieve 
data units from the data base. Data units may either be a data element, 
template, recipe or documentation aid description (docaid) . 

Data elements contain; 

* Source programs composed of programming language 
statements {51/ 1, COBOL, EOETEAN, etc.) 

* Text fox descriptions, manuals, etc. 

* Job Control (JCL) statements. 

Templates contain; 

* Statements in the data definition (template) language. 

Eecipes contain; 

* Statements in the document generation (recipe) 
language. 

* Text for literals. 

Documentation Aid Descriptions contain; 

* Statements describing programs to be used for documentation 
and debugging. 


COMMAND OPERANDS 

data-uni-t-name 


ELEMENT (SOUfiCECODE-TYPE) 

EOBTEAN 
PL1 
ASM 
COBOL 
JCL 

TEXT 

GRAPHICS 

RECIPE PRIVATE 

TEMPLATE COMMON . 

DOCAID 

CAPS 

ASIS 

CHANGE-NO [ = ] change- number 


EDIT 

E 
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datar unit- name 

the name of t.he data elements, templates, or recipes that you want 
to create or edit. {See data-unit naming conventions) . 

ElEHENT 

specifies the data unit to De edited is a data element, 
SODECECODE-TYPE 

specifies ahat language a data unit is written in. It must be 
specified for a new data unit only. The following is a list of 
sourcecode- types: 

FOHTEAN— states that the data unit identified by the first operand is 
for EOETEAN statements. 

PLI-states that the data unit identified by the first operand is for 
PL 1 statements. 

ASM-states that the data unit identified by the first operand is for 
assembler language statements. 

COBOL— states that the data unit identified by the first operand is 
fox COBOL statements. 

JCL-states that the data unit identified by the first operand is for 
job control language statements. 


TEXT 

specifies that the data unit is text. 


GHAP Hies 

specifies that the data unit is graphics. 

EECIPE 

specifies the data unit to be edited is a recipe. 

PRIVATE 

specifies that the TEHPLATE or BECIPE to be edited is stored in a 
private library. 


TEMPLATE 

specifies the data unit to be edited is a template. 


COMMON 

specifies that the TEMPLATE, or BECIPE to be edited is stored in a 
common library. 
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DOC AID 

specifies that the 5ata unit to be edited is a docaid. 


CAPS 

states that all input data is to be changed to uppercase characters. 
If you omit both CAPS and ASIS^ then CAPS is the default except when 
the data-element- type is TEXT. 


ASIS 

states that input is to retain the same form (upper and lowercase) 
as entered. ASIS will be the default for TEXT only. 

change- number 

a five digit number between 0 and 32I59. 

3.1 MODES OE OPERATION 


Input mode and Edit mode are modes of operation for the EDIT ccmmand. 

You enter data into a data unit in Input mode. You enter subcommands 
and operands in Edit mode. 

You must specify a data— unit-name when entering the EDIT ccmmand. If 
you do not, you are prompted for the name. The system places you in the 
Edit racde if your specified data unit is not empty; if the data unit is 
empty, you are placed in Input mode. 


3.1.1 INPUT MODE 


When in the Input mode, you type a line of data and then enter it into 
the data by pressing your terminal’s carriage return key or by entering 
another card. As long as yon are in Input mode, you can enter lines of 
data. One typed line of input becomes cne record in the data unit. 

Caution: the system adds a command or subcommand to the data unit as 
input data if you enter it while in Input mode. 

Line number: the system assigns a line number to each line as it is 
entered unless you specify otherwise. Line numbers make editing easier 
since you refer to each line by its own number, 

NOTE: All iuput records change to uppercase characters, except when you 
specify the ASIS or when the data unit you are editing specifies Text in 
the template. The TEXT operand also specifies that character- deleting 
indicators are recognized, but all ether characters are added to the 
data unit unchanged. 
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3.1.2 EDIT MODE 


When in ihe Edit mode, you enter subcommands to edit data units. By 
referring to the number, data units uith line numbers can be edited. 

This is called line-number editing. You also edit data by context 
editing. Context editing is achieved by utilizing subcommands that 
refer to the current line value or a character combination, such as with 
the PIED or CHAMGE subcommands, 

A pointer within the system indicates a line within the data unit. Upon 
initial entry into EDIT for. an old data unit, the current line pointer 
indicates the last line of the data unit. Otherwise, this pointer 
indicates the last line that you referred to. By using subcommands you 
change the pointer so it points to any line of data you choose. You 
then refer to the line that it points to by specifying an asterisk 
instead of a line number, figure 1 shows the position of the pointer at 
the completion cf each subcommand, 

NOTE: If the data unit does not contain a record zero, then a current- 
line pointer value of zero refers to the position before the first 
record. 

When editing data units, the line number field will not be involved in 
any modifications made to the record except during renumbering. 


3.2 CHANGING EEOM ONE MODE TO ANGTHEB 


You begin processing in Edit mode if you specify an existing data-unit- 
name as an operand, for the EDIT command- You will begin processing in 
Input mode when you specify a new data-unit-name or an old data unit 
with no records, as an operand for the EDIT command. 
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EDIT SDBCOMHAHDS VAIUE CF lOIHTEE AT EHE OF SOBCOHMAND 


ALTER 

BOTTOH 

CHANGE 

DELETE 


DOWN 


END 

FIND 

HELP 

INPUT 

INSERT 

Insert./ 

Replace/ 

Delete 


LIST 

RENUH 

SAVE 

TABSET 

TOP 

UP 


VERIFY 


Last line altered. 

Last line (or zero) for empty 6ata 
units- 

last line changed. 

Line preceding deleted line (or zero 
if the first line of the data units 
has been deleted) . 

Line n relatve lines below the last 
line referred to, where n is the 
value cf the * count' parameter, or 
bottom of the data unit (or line 
zero for empty data units). 

No change. 

Line containing specified string, if 
any-; else, no change. 

No change. 

Last line entered. 

Last line entered. 


Inserted line or replaced line or 

line preceding the deleted line if any 
(or zero, if no preceding line exists) . 
This is an implicit subcommand. 

Last line listed. 

Same relative line. 

No change. 

No change. 

Zero value. 

Line n relative lines above the 
last line referred to, where n 
is the value of the 'count* 
parameter, (or line zero for empty 
data units) . 

No change. 


FIGURE 1 VALUES OF LINE POINTER REFEREED TO BY AH ASTERISK 
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YOU will change from Edit mode to Input mode when: 

1- You enter the INDUT subcommand,' 

NOTE; Input -will begin at the specified line if you 
use the INPUT subcommand without the R (replace) 
keyword and the line is null (contains no data). 

Input will begin at the first increment past 
that line if the specified line contains data. 

If the INPUT subcommand is used with the R (replace) 
keyword then input begins at the specified line, 
replacing existing data, if any, 

2, You enter the INSERT subcommand with no operands. 

You will switch from Input mode to Edit mode when; 

1, . You press the carriage return key after typing only 
a semicolon or a punched card is read with a 
semicolon in the first column. 

2. There is no more space for records to be inserted 
into the data unit and reseguencing is not allowed. 

3. Nhen an error is encountered when reading or 
writing the data unit. 


3.3 TABULATION CHARACTERS (for on-line version only) 


Upon entering EDIT command into the system, a list of tab setting values 
are established by the system, depending on the data-unit-type. The tab 
setting values are logical and may or may not represent the actual tab 
settings on your terminal. By using the TABSET command, you can 
establish your own tab settings for input. 

The default tab setting values for each data-unit-type, is presented in 
the TABSET subcommand description. The system scans each input line for 
tabulation characters (the characters produced by pressing the tab key 
on the terminal) , Each tabulation character is replaced by as many 
blanks as are necessary to position the next character at the 
appropriate logical tab setting. 

Each tabulation character encountered in all input data is replaced by a 
single blank when tab settings are not in use. The tabulation character 
also separates subcommands from their operands. 
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3.4 TEBMIflATIWG THE EDIT COHHAND 


You may end the EDIT operation at. any time by switching to Edit mode (if 
you are not already in Edit mode) and entering the END subcommand. You 
should store all data before ending the EDIT command. To store the data 
use the SA7E subcommand. 


3.5 EDIT SUBCOMMANDS 


Subcommands edit or change data while in the Edit mode. The format of a 
subcommand is similar to the format of a command. Eigure 2 contains a 
description of each subcommands function- 
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SUBCOMJaaNDS 

ALTii 

BOTTOM 

CHANGE 

DELETE 

DOWN 

END 

BIND 

HELD 

INPUT 

INSEET 

In sert/ 

Heplace/ 

Delete 

LIST 

NOHBERS 

BENDN 

SAVE 

TABSET 

TOP 

DP 

VEEIEY 


FUNCTION 

1 

Allows use of characters not normally found on the 
keyboard. 

Moves pointer to last. line. 

Modifies text of a line, or range of lines. 

Hemoves lines. 

Moves pointer toward the end of the data. 

End the EDIT command, 
locates a character string. 

Defines available subcommands. 

Prepares system for data input. 

Inserts lines. 

Inserts, replaces or deletes a line. <Explicit subcommand.) 
Prints specific lines of data. 

Causes line numbers to be printed. ■ . 

Numbers or renumbers lines of data. 

Retains data units in documentation unit. 

Sets tabs. 

Sets pointer to the first line- 

Moves pointer toward beginning of the data unit. 

Causes current line to be listed whenever the current 
line pointer changes or the text is modified- 


FIGDRE 2 FUNCTIONS OF THE EDIT SUBCOMMANDS 
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3.6 BOTTOM Subcommand of EDIT 


The BOTTOM suicoramand changes the current line pointer so it points to 
the last line of the data unit being edited or so it contains a zero 
value, if the data unit is empty. 


SUBCOMMiND OPEEflNDS 

BOTTOM “ ~ 

B 


EXAMPLE I 

operation: Change the current line pointer so it points to 

the last line of the data unit. 

bpttom ; 
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3-7 ALTES/CHAUGE Subcom maTid of EDIT 


To modify a seguence of characters {character-string) in a line or in a 
range of lines use the CHANGE subcommand. You can modify either the 
first occurrence or all occurrences of the seguence. 

To replace a single character with a hexadecimal number (special 
character) , use the AITER subcommand. You may specify the hexadecimal 
number to replace a single character in a line or throughout the 
dbcume nt. 


SUBCOMMAND 

OPEBANDS 

CHANGE 

* 

C 

line-number- 1 [ line- number-2 ] 

* £count]-1 

AITEE 

A 

string-1 £ string-2 [special delimiter [A1L]3] 


CO ant- 2 


line-number- 1 

the number of a line you want to change. Rhen used with line- 
number-2, it gives the first line of a range of lines, 

line-number-2 

the last line of a range of lines that. you want to change. The 
lines are scanned for occurrences of the seguence of characters 
specified for string- 1. 


The line pointed to by the line pointer in the system is to be used. 
The current line will be the default value, if you do not specify a 
line number or an asterisk. 

count- 1 

starting at the position indicated by the asterisk, it gives the 
number of lines that you want to change- 
string- 1 

a seguence of characters (a character string)' that you want to 
change. The seguence must be preceded by an extra character which 
serves as a special delimiter. The extra character may be any 
printable character except a number, blank., tab, or asterisk. The 
extra character should not appear in the character string. Unless 
you intend for the delimiter to he treated as a character in the 
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character string, do not put a standard delimiter between the extra 
character and the string of characters. 

If you reguest string- 1 and not string-2, the specified characters 
are displayed at yonr terminal up to {but not including) the 
sequence of characters that you specified for string-1. You can 
then edit the sequence of characters as desired- When used with the 
ALTER subcommand, string-1 is either a single character or two 
hexadecimal digits- 

string-2 

a sequence of characters that you want to replace string-1. Like 
string- 1, string- 2 must be preceded by a special delimiter. This 
delimiter must be the same as the extra character used for string- 1. 
When used with the ALTER subcommand, string- 2 is either a single 
character or two hexadecimal digits. 


ALL 

every occurrence of string- 1 within the specified line or range of 

lines will be replaced by string-2. Only the first occurrence of 

string-1 will be replaced with string-2, if this operand is omitted. 

count— 2 

a number of characters to be shown at your terminal, starting at the 

beginning of each specified line. 

You can enter several different operand combinations. The system 
interprets the operands according to these rules: 

1. When entering a single number and no other operands, the system assumes 
you are accepting the default value of the asterisk and the number 

is a value for the count— 2 operand. 

2. When entering two numbers and no other operands, the system assumes the 
line-number— 1 and count-2 respectively. 

3. When entering two operands and the first is a number and the second 
begins with a character that is not a number, the system assumes 
they are line-number- 1 and string- 1. 

4. When entering three operands and they are all numbers, the system 
assumes they are line-number-1, line-number-2 and count-2. 

5. When entering three operands and the first two are numbers, but the 
last begins with a character that is not a number, the system 
assumes they are line-number-1 , line-number-2 and string-1. 
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EXAMPLE 1 

operation: Change a character sequence in a line of a line 

numbered data unit, 
known: line number is 96. 

Old character sequence is ILEMENT— TIPE. 

New character sequence is DATA UNIT, 


change xelement-typexdata unit; 


Example 2 

operation: Changing a character sequence «hen it appears in 

several lines of a line numbered data unit, 
known: Starting line number is -16. 

End line number is 52. 

New character sequence is THE. 

Old character sequence is THAT. 


change 16 52 ’that ’the ’all; 


NOTE: The blanks following string- 1 and string-2 are 
treated as characters. 


Example 3 

operation: Change part of a line in a line numbered data unit, 

known: line number is 164. 

Number of characters in the line preceding the 
characters to be changed is 13. 

change 164 13; 


NOTE; This causes the first characters of a line numbered 
164 to be listed. To complete the line, type 
in the new information and enter the line by 
pressing the return key. 


Example 4 

operation: Change part of a particular line of a line numbered 

data ■ unit, 

known: line number is 16. 

Character string to be change is * STHING-1. 


change 36 x’?' string- 1 ; 
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NOTE: line 16 is searched until the character string 
» ^string-1’ is found. The line is displayed up 
to the string. To complete the line, enter the 
new version into the data unit. 


Example 5 

operation; Change table values- 

knoHn: line number of first line in table is 267. 

' line number of last line in table is 304. 

Number of columns containing values is 9. 

change 267 304 9; 


NOTE: Each line of the table is displayed up to the 

column containing the value. As each line is 
displayed, enter the new value. The next line 
will not be displaced until the current line 
is changed and entered into the data unit. 

Example 6 

operation: Add a character seguence to the beginning of a line 

that is currently referred to by the pointer, 
known: character seguence is * TO BEHOVE ONE*. 


change * //to remove one; 


Example 7 

operation: Delete a character seguence from a line 

numbered data unit, 
known; line number is 5. 

Character seguence to be deleted is NEVER. 


change 5 /never//; 


or 


change 5 /never/; 
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3.8 BELETE Subcommand of EBIT 


To remove one or more lines from the data unit being edited use the 
BELETE subcommand, 

When the delete operation is ended, the current-line pointer points to 
the line that preceded the deleted line. If the first line of the data 
unit has been deleted, the current line pointer is set to 2 ero. 


SUBCOMEANB 

DELETE 

D 


OBEBANBS 

line-number-1 [line-number-2] 
* [count] 


line-numb er-1 

the line to be deleted or the first line of a range of lines to be 
deleted. 


line-number-2 ■ 

the last line of a range of lines to be deleted. 


the first line to be deleted is the line indicated by the current 
line pointer in the system. If no line is specified, this is the 
default. 


count 

starting at the location indicated by the preceding operand, it 
specifies the number of lines to be deleted. 


EXAMPLE 1 
operation; 

delete *; 


Delete a line referred to by the current line pointer, 

t 


or 


delete; 


or 
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HOTE: the last instance is a use of the Insert/Replace/ 


Delete function and not a DELETE subcoin laand. 


Example 2 

operation; Delete a particular line from a data unit, 
known; Line number is 10. 



Example 3 

operation; Delete consecutive lines of a data unit, 
known; Eirst line number is 6. 

Last line number is 55. 

delete 6 55; 


Example 4 

operation; Delete lines from a data unit with no line numbers, 

known; Number of lines to be deleted is 22. 


delete * 22; 


Example 5 

operation; Delete all lines of a data unit. 

known; Data unit contains 90 lines that are not numbered. 


top 

delete * 90; 
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3.9 DOWN Subcommand of EDIT 

To change the current-line pointer so it points to a line that is closer 
to the end of the data use the DOWN subcommand. 


SOBCOEHAND OPERANDS 


DOWN [count] 

DO 


count 

the number of lines toward' the end of the data unit that you want to 
move the current- line pointer. The default is one if you omit the 
operand. 

EXAMPLE 1 

operation: Change pointer sc it points to the next line. 


down; 


Example 2 

operation: change pointer so you can refer to a line that is 

closer to the end of the data unit than the current 
line. 

known: Number of lines from current position to new position 

is 6. 


do wn 6 ; 
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3-10 END SuJacommana of EDIT 


Use the END subcommand to end operation of the EDIT command. Upon 
entering the END subccmmand, you may enter new commands. If you have 
modified your data unit and have not entered the SAVE subcommand, the 
system asks you if you uant to save the modified data unit. If so, 
enter the SAVE subcommand. If you don’t want to save the data unit, re- 
enter the END subcomraand- 


SUBCOMMAHD OPERANDS 


END 
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3.11 FIND Subcotamand of EDIT 


To locate a specified sequence of characters use the FIND subcoiomaad. 

The system first IcoJcs at the line referred to by the current line 
pointer in. the system, and continues until the character string is found 
or the end of the data unit is reached. 


SUBCOHHAND ' “ 

OPERANDS 

FIND 

string [position] 

F 



string 

the sequence of characters {the character string) that you mnt to 
find. These characters must be preceded by an extra character that 
serves as a special delimiter. The extra character may be any 
printable character other than a number, blank, tab, or asterisk. 

Do not put a delimiter between the extra character and the string of 
characters. Xou must not use the extra character in the character 
string. 

The operands you specified the last time you used FIND during this 
current usage of EDIT are employed if you do not specify any 
operands. The system begins the search for the specified string at 
the line following the current line. Repeated use of this 
subcommand without operands allows you to search a data unit line by 
line. 

po si tion 

the column within each line at which you want the comparison for the 
string to be made. This operand also shows the starting column of 
the field to which the string is compared in each line. 

You must specify the digit 6 for the positional operand if you want 
to consider a string starting in column 6, Nhen using the position 
operand with the special delimiter form of notation for ’string*, 
you must separate it from the string operand with the same special 
delimiter as the one preceding the string operand. 
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EXAMPLE 1 

operation: Locate a character seguerce in a data unit, 

known: Character sequence is DIGIT , FOE. 

find xdigit for; 
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3. 12 INPUT Subcommand of EDIT 


The INPUT subcommand places -the system in the Input mode so you can add 
ox replace data in the data unit being edited. 


SUBCOMMAND 

OPESAKUS 



INPUT 

line-number {increment] 

R 

PROMPT 

X 


I 

HOPEGMPT 


line- number 

the location for the first new line of input and the line number. 
Input data will be added to the end of the data unit if no operands 
are indicated, 

increment 

the amount you want each succeeding line number to be increased. 

The default will be the last increment specified with the INPUT or 
EENDH subcommand if you emit this operand. If neither the INPUT or 
RENDM subcommand has been specified with an increment operand, an 
increment of 10 is used. 


the next new line of input will replace or follow the line pointed 
to by the current-line pointer, depending on whether you specify the 
E or I operand. If an increment is specified it is ignored. 


indicates you want to replace existing line of data and insert new 
lines into the data unit. If you fail to specify either a line 
number or an asterisk, this operand is ignored. The new line will 
replace the old line if the specified line already exists. The new 
line is inserted at that location if the specified line is vacant. 

It is important to remember that all old lines between the new lines 
of input will be deleted. 


I 


new lines to be inserted into the data unit without changing 
existing lines of data. If you fail to specify either a line number 
or an asterisk, this operand is ignored. 



DOHOHIC COMMAND REPEEE^ICE MAHUAX 
EDIT COEMAED 


PBOHDT 

indicates a line number to be displayed before each new input line 
and each time data is printed using the other subcommands. If the 
operand is omitted, the default is: 

1. The value (either PE CHET or NOEEOMPT) that was 
specified the last time you used Input mode. 

2. PHOHPT, if this is the first use of Input mode 

NOPROHPT 

indicates that you do not want to be prompted. 

EXAMPLE 1 

operation; Add and replace data in an old data unit, 

known j Data unit is tc contain line numbers. 

Prompting is desired'. 

The ability to replace lines is desired. 

First line number is 4. 

Increment value for line numbers is 4. 


input 4 4 r prompt; 


Example 2 

operation; . Insert data in existing data unit, 
known; Data unit contains text for a manual. 

Mo line numbers. 

Ability to replace lines is not needed. 

First input data is « NEM LINES TO BE INSEBTED* 
which is to be placed at the end of the data unit. 


input; 
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3. 13 ISSEBT Subcommand of EDIT 


To insert one or more new lines of data into the data unit, use the 
INSERT subcommand. Input data will be inserted following the location 
pointed to by the line pointer in the system. If you do not specify any 
operands, input data will be placed in the data unit line following the 
current line. By using the BOTTOM, DOHN, TOP, OP, EIND, and LIST 
subcommands, you can change the position pointed to by the line pointer. 


SUBCOMMANDS 

OPERANDS 


INSERT 

I 

[ insert-data ] 



insert- data 

the complete sequence of characters that you want inserted into the 
data unit at the location indicated by the line pointer. The system 
only recognizes a single delimiter. All except the first delimiter 
is considered to be input data if you enter more than one. 


EXAMPLE 1 

operation: Insert a line into a data unit, 

known: Line to be inserted is: * TEXT IS SODHCECODE*. 

The insertion follows line 24. 

The current line pointer is pointed at line 19. 
Oser is in Edit mode. 

Before entering the INSEHT-subcommand, the current line 
pointer must be moved down 5 lines to the location where 
the line is to be inserted* 


down 5 ; 


The INSERT subcommand is now entered. 


insert text is sourcecode; 
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Example 2 - 

operation; Insert several lines into a Eata unit, 
known; Data unit contains line numbers in increments of 10. 

Inserted lines to follow line 160. 

Current line pointer is at line 130. 

User operating in Edit mode. 

Lines to be inserted are: 

’USEE IS aSSEVEH* 

’PASSWOBD IS E7* 

‘DUI IS NaSlDOC’ 

BeEore entering the ISSEBT subcommand, the current line 
pointer must be moved down 3 lines so it points to 
line 160. 


down 3; 


INSERT subcommand is now entered. 


insert; 

NOTE; the system will respond with 
INSERT 

Lines to be inserted may now be entered. 
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3.14 Insert/Eeplace/Delete Enmction of EDIT 


The Insert/Eeplace/Delete function Inserts, replaces or deletes a line 
or data without indicating a subcoEraand name. If you want to insert or 
replace a line, simply specify the location and the new data. To delete 
a line, indicate the location. A line number or an asterisk should be 
used to specify the location. The asterisk tells you that the location 
to be used is pointed to by the line pointer within the system. Using 
the- UP, DOWN, TOP, BOTTOM, and FIND subcommands, you change the pointer. 


SUBCOMMAND 05EBANDS 

? 

line-number [ string J 
* 


line-number 

the number of the line you want to insert, replace or delete. 


indicates a replacement or deletion of the line at the location 
pointed to by the line pointer. You can use the TOP, BOTTOM, UP, 
DOWN and FIND subcommands to change the line pointer without 
modifying the data unit you are editing. 

string 

the sequence of characters that you want to either insert into the, 
data unit or t o re place an existing line. If a line exists at the 
specified location and this operand is omitted, the existing line is 
deleted. No delimiter is required between this operand and the 
preceding operand when the first character of 'string* is a tab. 

System Translation of Operands: when a line number or an asterisk is 
specified, the system deletes a line or data. When a line number or 
asterisk followed by a sequence of characters is specified, the system 
replaces the existing line with the specified sequence of characters or, 
if there is no existing data at the site, the system inserts the 
sequence of characters into the data unit at the specified location. 


EXAMPLE 1 

operation: Insert a line into a data unit, 

known: The number to be assigned the new line of data is 

46 and the line is TESTTEMP COBOL A. 


46 testtemp cobol a; 
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Example 2 

operation: 

known;' 


Replace an existing line in the data unit. 
Huuibexea line to be replaced is 35. 
Beplacement data is 04 SAME PIC X (30) . 


35 04 name ric x(30); 


Example 3 

operation; Replace an existing line of a data unit that 
does not have line numbers, 
known; Line pointer is pointing to 

the line that is to be replaced. 

Replacement data is MASTER TABLE. 


* master table 


Example 4 

operation: Deleting a line, 

known: Line number is 627. 

Current line pointer points to line 627. 


627; 


or 
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3.15 I.IST Subcoffiraand of EDIT 


To display one or more lines of jour data unit af your terminal or on 
the printer, use the XIST subcommand. 


SUBCOMMAND OPEEAHDS 


LIST line-nurober-1 [ line-number- 2] 

L * [ count ] 

NDM 

SNDH 


line-number- 1 

the number of the line that you want to be displayed at your 
terminal or on the printer, 

line-number-2 

the number of the last line that you want displayed. All the lines 
from line number 1 through line number 2 are displayed when you 
specify this operand. 


the line referred to by the line pointer in the system is to be 
displayed at your terminal or on the printer. By using the UP, 
DOWN, TOP, BOTTOM, and FIND subcommands without modifying the data 
unit you are editing, you can change the line pointer. 


NDM 

line numbers are to be displayed with the text. If both NDM 
and SNUM are omitted, this is the default value, 

SNUM 

line numbers will not be printed on the listing. 

NOTE: If no numeric operand or asterisk is present, the entire 

data unit will be deleted. 


Example 1, 

operation; Listing an entire data unit, 
list; 
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Example 2 

operations Listing part of a line-nuraliered data unit, 
known: The first line to be displayed is 66. 

The last line to be displayed is 104. 


list 66 104; 


Example 3 

operation: Listing part of a data unit without numbers, 

known: Tie line pointer in the sytem currently points to 

the first line to be listed. 

The copy consists of 22 lines. 

list * 22; 


Page 47 





DOflONIC COMMAND REFERENCE HANUAl 
EDIT COMMAND 


3.16 NDHBEES Subcommand of EDIT 


The NUMBERS subcommand causes line numbers to be printed each time data 
is printed. This is the system default. It works in conjunction ¥ith 
the prompt feature of INPUT. 


SUBCOMMAND OPERANDS 

NUMBEis ON 

NUM OEF 


indicates that you want to have the line numbers printed each 
time data is printed. If you emit both ON and OFF, this is 
the default. 


OFF 

indicates that you want to discontinue the printing of line 
numbers as data is printed. 


Example 1 

operation: line numbers reguested with data. 


numbers on; 


Example 2 

operation; Discontinue line numbers. 


numbers off; 
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3.17 EEHDH SubccKunaud of EDIT 


Use the EENUM subccBiinand to assign a line number to each record of a 
data unit that does not have line numbers and to renumber each record in 
a data unit that has line numbers. 

In all cases, the specified for default) increment value becomes the 
line increment fox the data unit. 


SDBCOaaAND OPEBAMDS 


SENOH £ new- line-number [increment £ old-line-number }]] 

REN 


new-line-number 

the first line number to be assigned to the data unit. The first 
line number will be 10 if this operand is omitted. 

increment 

the amount by which each succeeding line number is to be 
incremented. The default value is 10. Unless you specify a new line 
number, you cannot use this operand- 

old— line- number 

the site within the data unit where renumbering begins. Renumbering 
will start at the beginning of the data unit if this operand is 
omitted. Unless you specify a value for the increment operand, you 
cannot use this operand. 

EXASPIE 1 

operation: Renumber an entire data unit. 


renum; 


NOTE: Successive line numbers in the data unit will be 10, 20, 

30, etc. See default values for new line number and increment. 


Example 2 

operation: Renumber part of a data unit, 

hnown: Old line number is 72. 

New line number is 64 and the increment is 1, 


ren 64 1 72; 
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Example 3 
operation; 

known: 


Benambex part of a data anit from which lines have been 
deleted. 

The data unit contained lines 90, 100, 110, 

120 and 130 before deletion, lines 100 and 
110 were deleted, lines 120 and 130 are to 
be renumbered with an increment of 10. 


ren 100. 10 120; 


NOTE; the lowest acceptible value for a new line number in this 
example is 91. 
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3.18 SAVE Subcommand of EDIT 


Ose the SAVE subcommand to permanently 1?eep your data unit. The updated 
version replaces tie original if an operand is not specified; both are 
available for further use if you specify a new name. 


SDBCOfiEAND OPEEANDS 


SAVE data -u ni t- n am e, 

S 


ElEMEHT 

TEKPIATE COEMON 

■EECIPE PEIVATE 

DOCAID 

[CHAEGE-SO [=3 Change-number] 


data-u nit-name 

the name assigned to your edited data unit. It is the default. The 
data-unit-type may not be chanced during SAVE. 

ELEMENT 

specifies that the data unit is an element. 

TEMPLATE 

specifies that the data unit is a template. 

COaflON 

indicates the recipe, template or docaid is in a common library. 
HECIPE 

specifies that the data unit is a recipe. 

PRIVATE 

indicates the recipe, template or docaid is in a private library. 
DOCAID 

specifies that the data unit is a docaid. 
change-number 

a five digit number between 0 and 32759. 
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EXAMPLE 1 

operation: Save the data unit that has just been edited. 

Jaiown: ‘ User supplied name Is ASSEVEN. 


save arseven; 
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3.19 TABSET Subcommand of EDIT 


Use the TABSET subcommand to create or change the logical tabulation 
settings or to void any existing tabulation settings. 

The TABSET subcominand causes each strike of the tab key to be translated 
into blanks corresponding to the column requirements for the data-unit- 
type. Tor example, if the name of the data unit being edited has COBOL 
as the sour cecode- type, the first tabulation setting sill be in column 
8. The values in the figure below will be in effect when you first 
enter the EDIT command. 


Tab Settings 


TEXT 

5, 

10, 

15, 

20, 

3 0, 

40 

GSIPHICS 

5, 

10, 

15, 

20, 

30, 

40 

(SOURCECODE) 

ASM 

10 

, 16 

/ 31^ 

72 



JCl 

10 

, 20 

, 30, 

40 

, 50 

, 60 

COBOL 

8, 

12, 

72 




POETBAH 

7, 

12 





PL/1 

5, 

10, 

15, 

20, 

25, 

30, 


35, 40, 45, 50 


It may be to your advantage to have the mechanical tab settings coincide 
with the logical tab settings- The logical tab positions are calculated 
beginning at the next position after the prompt since a printed line 

number prompt is not logically part of the data you are entering. It 

follows that if you are receiving five-digit line number prompts and 
have set a logical tab in column 10, the mechanical tab should be set 15 

columns to the right of the margin. The mechanical tab should be set 10 

columns to the right of the margin if you are not receiving line number 
prompts. 


SUBCOMHAND OPEBABDS 


TABSET OH [integer-list] 

TAB OPE 

IMAGE 
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ON integer- list 

tal5 settings are to be converted into blanks by the system. The 
existing or default tab settings are used if you specify ON without 
an integer— list- You can create new values for tab settings by 
indicating the numbers of the tab columns as values for the integer- 
list. A maximum of 10 values is allowed. The default value is ON 
if you omit both ON and OFP, 


OF? 

there is to be no interpretation of tabulation characters. Each 
strike of the tab key produces a single blank in the data. 

IMAGE 

the next input line will define new tabulation settings. The' next 
line that you type should consist of ’t*s, specifying the column 
positions of the tab settings, and blanks or any other characters ' 
except ’t*. The uaximum number of tabs allowable is 10 settings. 
You should never use the tab key to produce the new image line. It 
is a good practice to use a seguence of digits between the *t’s so 
you can easily determine which columns the tats are set to. 


EXAMPLE 1 

operation: Ee-establish standard tab settings, 

known: Tab settings are not in effect. 

tab; 


Example 2 

operation: Establish 'tabs for columns 6, 46, and 66. 


tab on (6 46 66) ; 


Example 3 

operation: Establish tabs on every fifth column. 


tab image 
1234t1234t123... ; 
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3.20 TOE Subcommand of EDIT 


To change the line pointer in the system to the first line, use the TOE 
subcommand. 

Xf the data unit is empty, then the line pointer will be set to zero and 
the message input ■will be printed. 

The TOE subcommand is useful in setting the line pointer to the proper 
position for subseguent subccuimands that need to begin their operations 
at the start of the data unit. 


SUBCOBMND 


OEEBAHDS 


TOE 



EXAMELE 1 

operation: Pind the first occurrence of ^template* in the data 

unit. 


top 

find ’template*; 



Eaoe 55 




DOMONIC COHUAND EE¥EEENCE KAMUAL 
EDIT CO H HA HD 


3.21 UP Subcommand of EDIT 


To change the line pointer in the s;ystem so it points to a record nearer 
to the start of the data’ unit, use the UP subcommand. You are notified 
if the use of this subcommand causes the line pointer to point to the 
first record of the data unit. 


SUBCOUHAND 


OPERANDS 


UP 


£count ] 


! 


count 

the number of lines toiifard the start of the data unit that you want 
to move the current line pointer. The pointer is moved only one 
line if the count is omitted. 


Example 1 

operation: Change pointer to point to preceding line. 


up; 


Example 2 

operation: Change the pointer so it refers to a line that is 6 

lines before the currently referred to line. 
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3.22 ¥EE2FY SulacoiBinand of EDIT 


The VERIFY STihcommand displays -the line that is currently painted to by 
the line pointer in the system; whenever the current line pointer has 
been moved, or whenever a line has been modified by use of the CHANGE 
subcommand- You will ha.ve no verification of changes in the position of 
the current line pointer until you enter VERIFY. 


subcoemand'' 


OPEE-ANDS 


VERIFY 

ON 



V 

OFF 




indicates that you want to have the line that is referred to by the 
line pointer displayed each tiite the line pointer changes or .each 
time the line is changed by the CHANGE subcommand. If you omit both 
ON and OFF, this is the default- 


OFF 

indicates that you want to discontinue service. 


EXAMPLE 1 

operation,; Display the line referred to by the line pointer each 
time the line pointer changes. 


verify ; 


or 


verify on; 


Example 2 

operation; End operation of verify subcommand. 


verify off; 
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^.0 EBASE Command 


Use the ERASE command to remove a permanent data unit from a 
documentation unit. Once a data unit has been erased it can no longer 
be retrieved as an old data unit lay issuing an EDIT command. Any 
reference to it will he as a new data unit. The format for the ERASE 
command is: 


COMMAND OPERANDS 


ERASE data unit name 

R 


ELEMENT 

DOCAID 

RECIPE COMMON 

TEMPLATE PRIVATE 

£ CHANGE-NO [ = ] change- number ] 


data-unit-name 

the name of the data elements, templates, recipes, or docaids 
you want to erase. 

ELEMENT 

specifies that the data unit to be erased is a data element. 
DOCAID 

specifies that the data unit to he erased is a docaid. 

RECIPE 

specifies that the data unit to be erased is a recipe, 

COMMON 

specifies that the recipe, docaid or template to he erased is 
stored in a common library. 

TEMPLATE 

specifies that the data unit to be erased is a template. 
PRIVATE 

specifies that the recipe, docaid or template to be erased is 
stored in a private library. 
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change-number 

five digit number between 0 and 3275S. 


Example 1 

operation; Erasing a data unit. 

known; Data-u nit-name is SYSTEE-BICCK-DIAGBAE, 


erase system-block- Siagram; 


If the data unit is found 
want to permanently erase 
decide to erase and NO is 


the system will prompt you to be sure that 
the data unit. Your answer is YES if you 
you decide not to erase. 



you 
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DEEINE mSA-SYSTEM USING SPASM 1, 8SUBSCPE EECIPE-CX ASS=5 

/*THIS IS THE HIGHEST LEVEL RECIPE OE A SET OE RECIPES NECESSARY 
TO PRODUCE A DOCUMENT EEOM THE DATA STORED UNDER TEMPLATE NASA 
-SYSTEM*/ 

STREAM SPRINTER TO PRINTER; 

/*SET OUTPUT NAME SPRINTER TO POINT TO LOGICAL NAME PRINTER*/ 
STREAM SOBJSET TO BISKI 

/*POINT OBJECT MODULES TO PERMANENT DISK DATA SET*/; 

LITERAL ’DOMONIC* OUTPUT IS (SPRINTER , + 20) 

/*TITLE TO BE PRINTED 20 LINES DEEP ON A NEN PAGE*/; 

SYSTEM-OVER VIEN OUTPUT- (, 5) . - 

/★ROUTE THE DATA-ELEMENI SPARM1 TO THE SAME OUTPUT 
STREAM AS THE PREVIOUS LITERAL. IIVE BLANK LINES 
ARE INSERTED BEEORE PRINTING */, 

END NASA-SYSTEM; 


EIGURE 3 


EXAMPLE OE A SIMPLE RECIPE 



DOMONIC COMMAND BEFBBENCE MANOAL' 
SECIPES AND DOCUMENT GENEBATION 


DEFINE HASA-STSTEM USING SPABH1, DSUEBCPE RECXPE-CL1SS=7 

/*THIS IS THE HIGHEST LEVEL OP A SET OP RECIPES NECESSARY TO 
. PEODUCE A DOCUMENT PBOM DATA STORED UNDER TEHPLATE-NASA- SYSTEM V 
STREAM SPEINTEH TO PRINTEE; 

/*SET OUTPUT NAME SPRINTER TO POINT TO LOGICAL NAME PEINTER*/ 

STREAM SOBJSET TO DISKi 

/♦POINT OBJECT MODULES TO PERMANENT DISK DATA SET*/! 

LITERAL ’DOMONIC* OUTPUT IS (SPRINTER, +20) 

/♦TITLE TO BE PRINTED 20 LINES DEEP ON NEN PAGE*/; 

SY STEM-0 VERVIEU OUTPUT== (,5) 

/♦ROUTE THE DATA-ELEMENT BPABH-1 TO THE SAME OUTPUT STREAM 
AS THE PREVIOUS LITERAL. , PIVE BLANK LINES ARE INSERTED 
BEFORE PRINTING ♦/? 

CALL SUBSYSTEM-HANDLER USING EDITOE-SDESYSTEM , CALL, EDITOR, CALL, 
SSAEE,CALL,EI8PUT 

♦/GET SUBRECIPE FOR DOCUMENTING TEE RECIPE*/ 

DEFINE SUBSYSTEM-HANDLER USING SSUBSYS , SVERB 1 ,SHOD1 , SVERB2, 
SMOD2,SVEEB3,£MOD3 EECIPE-CL ASS=5 

/♦A RECIPE TO HANDLE DOCUMENTATION OF A SUBSYSTEM*/ 

LITERAL 'EDITOR-SUBSYSTEM* OUTPUT IS (SPRINTER, +0 ,2 0) 

/♦PRINT SUBSYSTEM-NAME AT TOP OF PAGE */ 

T12 (EDITOR-SUBSYSTEM) OUTPUT IS (SPRINTER) 

/♦WRITE THE SUBSYSTEM ABSTRACT*/ 

/♦THE FOLLOWING INSTRUCTIONS ARE PROTOTYPES TO HANDLE 
SUBSYSTEM MODULES*/ 

CALL MODULE-HANDLER USING EDITOR, SPRINTER 

DEFINE MODULE-HANDLER USING SPGM1, SOOTPDTl RECIP E-CLASS=3 

/♦A RECIPE TO HANDLE INDIVIDUAL MODULES IN A SUBSYSTEM*/ 
LITERAL ’EDITOR’ OUTPUT IS (SPRINTER, 3) 

/♦PRINT MODULE NAME AFTER SKIPPING 3 LINES*/ 

T13 (EDITOR) OUTPUT IS (SPRINTER) 

/♦PRINT THE MODULE ABSTRACT*/ 

SCOBTIDY INPUT = T7 (EDITOR) , OUTPUT = (lEDITOR) 

/♦INVOKE COBOL TIDY PROGRAM FOR SOURCE MODULESj TIDIED 
SOURCE SAVED ON TEMPORARY DATA SET*/ 

SCOBCOHP INPUT = (SEDITOR) , OUTPUT = (SPRINTER, SORJ SET) 

/♦INVOKE COBOL COMPILER; SOURCE INPUT IS FROM PREVIOUS 
DATA SET; PRINTED OUTPUT GOES TO SOUTNAME, OBJECT CODE 
GOES TO SOBJSET*/ 

END MODULE-HANDLER; 

END SUBSYSTEM-HANDLER; 

END NASA-SYSTEM; 


FIGURE t} EXAMPLE OF AN EXPANDED RECIPE 
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5.0 BECIPES AND DOCUMENT GENEEflTION 


The vehicle for producing output from DOMONIC is the recipe. Recipes 
provide the link ietween raw data stored in the docuraentaticn unit and 
development and documentation aid programs which produce outpot- 
Examples of documentation aids are compilers, linkage editors, text 
formatters, flowcharters and cross reference generators. 

Recipes may be simple or complex. A simple recipe might be a recipe to 
compile a single program and produce a listing, A complex recipe such 
as one to produce a user*s manual combines many data units with many 
output producing programs and formats all outputs into a document with 
table of contents, chapters, headings and page numbering. A recipe is a 
combination of data unit names from the documentation unit, names of 
output producing programs and instructions for processing and formatting 
the overall document. 

The recipe is written in the recipe language. It is entered into the 
documentation unit through the editor and stored for immediate or future 
use. All editor facilities can be used to input and update the recipe. 
The editor treats a recipe as if it were text and does not interpret 
recipe instructions. 


5,1 DOCUMENT GENERATION 


The goal of document generation is to make the production of documents 
as easy as possible. In order to do this three entities used in 
document generation must be specified in advance- These are a recipe, a 
documentation or development aid description {docaid) and a Icgical- 
physical device table <L—P table) . All are part of the documentation 
unit. In addition, another table, the input-output stream table, is 
automatically built during the generation process. This table is not 
retained after document generation. The recipe, docaid, L-P table and 
input/output stream table are used during the recipe expansion and 
document production process. 

The actual document production is a separate batch job executed 
independently of the system. The job stream for this batch job is 
created during the recipe expansion process performed under the control 
of DOMONIC. when the job stream has been created, it is written to a 
HASP internal reader. (For systems without HASP, the job stream is 
written on a disk and an OS reader must be started using an operating 
system command) . 
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5.2 HECIPE EXPANSION PBOCESS 


The recipe expansion process compiles a job stream ^sequence of job 
control language statements) which produces a document from a group of 
specified inputs. Before explaining the recipe expansion process the 
various inputs are described. 

5. 2. 1 Recipe 

A recipe is a sequence of instructions written in the recipe language 
describing how a document is produced. Recipes can be used as main 
recipes or as subrecipes. Recipes may be- defined with parameters. This 
allows the writing of general purpose recipes in which the names of data 
elements or documentation aids are specified when the recipe is invoked. 
If a recipe is defined with parameters, the corresponding arguments must 
be supplied in the GENERATE command or CAll. Op to four levels of calls 
are permitted. 

5.2.2 Documentation Aid Description 

A documentation aid description (docaid) is similar in many ways to an 
IBM assembly language macro definition- It consists of a docaid 
prototype statement and a series of model statements. The' prototype 
statement gives the name of the docaid and its symbclic parameters. The 
model statements model job control language (JCX) statements and control 
cards. One or more job steps are generated from the model statements. 

The symbclic parameters of the docaid prototype statement are divided 
into three classes; inputs, outputs and options. Its format is; 


Sdocaidname [INPUT [ = ] ] [OUTPUT [=} (o- 

1, ...)£[ OPTIONS [ = ] {p-1,...) ], 


docaidname 

the name by which the documentation aid will be referenced. 
Syntax is the same as for template and recipe names. 


a list of input parameters. They correspond to inputs specified 
in the model statements. There are two types: 

da ta-uni t-names 

usually the name of a data element, but could be a template, 
recipe or docaid (last three treated as text) . A data-unit 
input parameter generates a DD * statement in the job 
stream. It is followed by the data retrieved from the data base. 

/^5 
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i— o stream aame 

the name of an inpat data set generated ty a previous 
step in the document production. Ihe name must start 
with a $ followed by alphabetic character concatenated 
with zero to six more characters. 

0-1 

a list of i— o stream names used for output from this documentation 
aid (may later be inputs to other docaids) . They correspond 
to outputs in the model statements. 

p-1 

a list of option parameters used as simple replacement parameters 
in the model statements. If a parameter contains multiple 
items, it must be enclosed in parentheses. The whole character 
string without the parentheses will be used in replacement. 

An input, output, or option parameter is referenced in the docaid model 
statements according to the following ccnvention; 


SXnn 


where 

S is reguired and marks this as a replaceable parameter. 

X is one of the letters 1,0 or E for input, output, 

option respectively. 

n{n) is a one or two digit number uniquely defining the 
parameter within its class. 

Docaids are entered using the editor and stored in the private library 
for the documentation unit or in the system common library. 

5.2.3 Logical Stream-Physical Device Table 

The -logical-stream-physical device table (L— P table) links logical 
input/outpat streams used in a recipe to actual physical devices. The 
table is entered into the recipe library for a documentation unit by a 
JCL programmer using the editor. Any number of these tables may be 
entered into the recipe library, each with a unique name. The table to 
be used in a recipe expansion is designated in the GENERATE - command- If 
none is specified., the system L-P table is used. 
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Each entry in this table has two parts; 1) a logical stream name and 2) 
a JCL phrase defining the physical device. For example a logical stream 
with the name PSINTEB could define a physical device with JCL phrase 
SYSOOT=A. The format for table entries is; 


L [=] iogical-stream-name, P [=] physical-device-JCI- phrase; 


An L-P table can be listed either in the form it was input by using the 
editor or formatted by using the LISI subcommand of the GENERATE 
command. 

The logical stream names are associated with input and output parameters 
used in docaids by using a stream instruction. (See Section 5.3-7.) 

The recipes, docaids and the L-P tables are all members of the library 
of a documentation unit. They are permanent in nature. They must all 
exist before a GENERATE command is issued. 

In addition a temporary table (input— output stream table) is created 
only for the duration of the recipe expansion. 


5.2.4 Input-Output Stream Table 


This table contains a list of correspondences between input and output 
names used in recipes and logical stream names in the L-P table. The 
assignment of a inpnt or output name to a logical stream is done by the 
stream instruction in a recipe. The assignment is only valid for a 
given recipe expansion and document generation. 

It can be changed within the same expansion or from one recipe expansion 
to another. This allows you to direct inputs and outputs to different 
devices without changing input and output parameters in recipes. 


5,3 RECIPE INSTRUCTION LANGUAGE 


A recipe is composed of a sequence of character strings called 
instructions. These instructions define the inputs to be used, where 
the output is to be placed and the documentation aids to be used to 
generate the output. The general format for a recipe instruction is; 


instruction-name [operands] [/^explanation*/!; 
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The instruction name is taken from the set of instruction names: DEFINE, 
END, CALL STEEAH, $DOCAID, LITERAL, DAT A- UNIT or DU MMX. The total 
length of the instruction-name an3 operand fields may not exceed 980 
characters after any variable parameters have been replaced with real 
arguments. The operands are determined by the syntax particular to the 
instruction and the explanation is any character string. 


5.3.1 Define Instruction 


The define instruction names the recipe. It is the first instruction 
and marks the recipe's beginning. Its format is; 


DEFINE recipe- name [USING {5parm-1 , . . 1 [ EECIPE-CIASS [=] n] 

[ /*€X plana tion*/ ] ; 

recipe- name 

the name of the recipe being defined. It can be from 1 to 30 
characters {alphabetics, digits, dashes, underscores) long and 
must start with an alphabetic character. 

Sparra- 1 

a list of parameters replaced by real values (arguments) 
when the recipe is called from the library to generate outpnt. 
Parameters are alphanumeric, 1 to 8 characters long and must start 
with an ampersand. 

n 

an integer in the- range 0-9 which denotes the class of this recipe. 
This field is compared to a nser's recipe authorization for permission 
to use this recipe. Class 0 is for the simplest recipes while 
class 9 is for the most complex. Eecipes with a class of 7 or 
higher may only be generated using the batch version of DOHONIC. 

If the RECIPE-CLASS phrase is emitted from the DEFINE instruction, 
a. class value of 9 is assumed. 

explanation 

a character string explaining the recipe. 


5.3.2 End Instruction 


The- end instruction marks the end of a recipe. Each recipe must begin 
•with a DEFINE instruction and end with an END instruction. The format 
for the end instruction is; 

m 
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END [ recipe- name ] [/^explanation*/]; 


recipe- name 

The name of the recipe being defined. It can be from 1 to 30 
characters (alphabetics, digits, dashes, underscores) long and 
mast start with an alphabetic character. 


expla nation 

a character string explaining the recipe. 


5.3. 3 Call Instruction 


The call instruction is used to invoke a recipe from another recipe. 

This instruction can be thought of as a ’subrecipe* call. Arguments may 
be passed to match the parameters defined for the recipe. The format 
for the call instruction is; 


CALL recipe-name [USING {arg-l,,,.)] [ /^explanation*/] 


recipe-name 

a valid recipe name. 


arg-1 

a list of arguments corresponding to the parameters defined for 
the called recipe. Each argument is a character string with 
a maximum length of 510 characters. If an argument contains 
a comma, the argument should be enclosed in parentheses. 

The parentheses are not considered to be part of the 
argument. 


explanation 

any character string. 


5.3,4 Literal Instruction 


The literal instruction is used to insert a literal into the output 
stream {usually the printer) , The literal instruction format is: 


[LITERAL] ‘literal-string* 

[OUTPUT [ = ] ([ output-name ][ ,sklp-n ])] ] 
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[ /^explanation */ }; 


lite ral- string 

a character string- If a single gaote is desired within the 
literal string, two guote marks must be used together, 

oatput-name 

the name of the output stream to which the literal is to be 
routed. If not given, the I-O NAME $PEINTEE is the 
default, 

skip-n 

an integer specifying the number of lines to be skipped from 
the current position before outputing this line. To start 
a new page and then skip n lines precede the integer with a 
plus sign, e.g. +io. A value of zero will suppress skipping 
to a new line. The default is 1 line, 
explanation 

any character string. 


5.3,5 Data— Unit Instruction 


The ' data-un it instruction is used to retrieve a data unit and route it 
to a designated output stream (usually the printer) for inclusion in the 
document. The format for the data— unit instruction is: 


[LIST] (data-unit-name-1, ,, ,) 

[OUTPUT [ = ] ^[ output-name ][, skip-n ]) ], [/^explanation*/ 3 ? 


data- unit-name- 1 

a list of data units to be retrieved and output. If more than 
one data-unit is listed the data retrieval will be concatenated 
on output. 


outp ut-name 

the name of the output stream to which the data units are to be 
routed. The I-O KANE SPEINTEE is the default if no output 
option is given. The output line format will depend on the 
data unit type. Elements of type sourcecode and docaids 
will have each line expanded’ tc an 80-character card 
image with data left justified. For templates, recipes and 
elements of type text and graphics, the data will be divided 
into 132 character printer lines. Each line of the data 
unit will start on a new line. Data unit lines longer 
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than 132 characters will be continued on subseguent 
printer lines. 

skip-n 

an integer specifying the number of lines to be skipped from the 
current position before outputting this line- lo start a new 
page and then skip n lines, precede the integer with a plus sign, 
e.g. +10. A value of •zero will suppress skipping to a new line- 
Ihe default is 1 line. 

explanation 

any character string- 

5.3.6 SDocaid Instruction 

The Sdocaid instruction invokes a development or documentaticn aid. The 
JCL necessary to execute the appropriate docaid program during the 
generation of a document is assembled. The operands of this instruction 
names the inputs, outputs and options to be used for this execution of 
the documentation aid program. The operands are used to replace the 
dummy parameters in the docaid model statements. The format for the 
$docaid instruction is: 


$docaid-name [INPUT [=] (input-name- 1 ] 

[OUTPUT [ = ] (output-name-1,...) ] 

[OPTIONS £=] (option-1,...) 3 [/^S'explanationV]; 


docaid-na me 

the name of the docaid in the recipe library, follows the rules 
for forming template and recipe names. 

in put- name- 1 

a list of data unit names (usnally data element names) or input 
names which refer to input streams or temporary data sets. 

An input name starts with a $ followed by an alphabetic character 
followed by 0-6 alphabetics and digits. 

output— name- 1 

a list of output names referring to output streams or temporary 
data sets. The name formation rules are the same as for input 
names. 
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option- 1 

a list of options for the documentation, aid program. Each option 
can be any character string up to 100 characters in length. 


explanation 

any character string-. 
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5-3.7 Stream Instruction 


The stream instruction assigns input and oniput-names {i-o names) used 
as arguments in a $docaid, literal or data— unit instruction to logical 
input/output (i-o) streams- The Icgical i-c streams must correspond to 
existing entries in the 1-P table. The format for the stream ’ 
instruction is: 


STREAM i— o-name TO logical-stream-na me £/=»explanation*/J; 


i-o name 

an input or an output name used in a Sdocaid, literal or 
data-unit. instruction. 

logical-stream-na me 

the name of a logical i-o stream in the 1—P table given in the 
GENERATE command. 


explanation 

any character string. 


5-3.8 Dummy Instruction 


The dummy instruction is an instruction that does nothing- It is a * no- 
op* instruction. It will most commonly be used as an instruction 
generated as the result of the replacement of a recipe parameter by the 
argument * DUMMY* in a recipe call. The format for the dummy instruction 
is: 


DUMMY [any character string]; 


The dummy instruction is used to vary the documentation aids invoked or 
the output produced by a recipe. Eor example, suppose we have two 
recipes, RECIPE- 1, RECIPE— 2 and data element SYSTEM— ABSTRACT where 
RECIPE- 1 calls EECIPE-2. 

DEEINE RECIPE-1 RECIPE-CXASS-1 ; 


CAIL RECIPE-2 USING , , SYSTEM- ABSTRACT ; 
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CALL EECIPE-2 USING , , DUMMY; 

END SECIPE-1; 

DEFINE EECIPE-2 USING , ,SINS'T1 EECIPE-CLASS-2 

/*list out data elements V; 


SINST1 OaTPUT=$PHINTES 


END EECIPE-2; 

HECIPE— 1 calls BECIPE— 2 tuice. The first time it lists 

SYSTEM- ABSTEACT , the second time nothing is listed. If the following 

command is issued 


GENEEATE EECIPE-1; 


in the expanded EECIPE-1, HECIPE-2 expands to a data unit instruction 
and a dummy instruction 


SYSTEM-ABSTEACT OUTPUT=$PEINTES 


DUMMY OUTPUT=$PHINTEE 


This example of the dummy instruction also serves an an introduction to 
the subject of recipe expansion. 
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5.4. GENERATE CommaTia 


TAe recipe expansion process siarts Hith a GENERATE command. The 
command names the recipe to be used, supplies recipe arguments and 
identifies the logical stream-physical device table (L-P table), to route 
outputs generated. The format of the GENERATE command is: 


COMMAND 

OPERANDS 


GENERATE recipe— name 

[USING arg-1,.,.] 

[I-O-TAELE [=3 1-p-table-name] 



recipe- name 

the name of the recipe being defined. It can be from 1 to 30 
characters (alphabetics, digits, dashes, underscores) long and 
must start «ith an alphabetic character. 

arg-1 

a list of arguments corresponding to the parameters defined 
for the called recipe. Each argument is a character string with 
a maximum length of 510 characters. If an argument contains 
a comma, the argument should be enclosed in parentheses. 

The parentheses are net considered to be part of the 
argument. 

1-p- table-name 

the name of an L— P table which links logical i— c streams 
used in a recipe to actual physical devices. 

Yon first enter a GENERATE command. The command is parsed and 
the recipe is searched for the required L-P table. If it 
found, it is assembled and stored in working storage. 

The system returns to you for a subcommand. 

The GENERATE command has six subcommands. They are SCAN, PROOF, RUN, 
LIST, HELP, and END. Hone of these subcommands require operands. 
However, the PROOF subcommand does allow the use of an operand *WITH 
JCL', The format is the subcommand name followed by a semicolon. 
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5.4.1 SCAN Subcojnman a of GENEEATE 


Use the SCAN sn he ora maud of GENEBAfE to do syntax checking of lecipes. 

The SCAN starts with the first line of the main recipe and proceeds 
through the recipe line hy line, expanding the recipe calls as it goes. 
Each line is checked for correct syntax- The entire expanded recipe is 
listed hack to the user with sub-recipe calls indented- 


SU3C0HMAND 


OPEBANDS 


SCAN 


Example 1 

operation: Scanning a recipe. 

known: Name of recipe is COMPILE- AND— LIST, 


generate comp ile-and- list; 

ENTEB GENERATE SUBCOMMAND, 
scan; 

DEEINB COMPILB-AND-LIST RECIPE-CIASS IS 2 
» SYSTEM OVERVIEW* OUTPUT = ($LISTING,+) 

SYSTEM-OVEEVIEB 0UTP0T=(,3) 

CALL COBOL-CGMPILE USING (BECIPE,RGETDATA) ,CLIST 

DEFINE COBCL-COMPILE USING SHODNAME, fiPABM BECIPE-CLASS IS 0 
SCOBCOMP INPUT=CODE <BECIPE,BGETDATA) , OPTIONS=CLIST 
END COBOL- COMPILE 

STREAM SPBIHTEB TO PBINTEB 

* MODULE BGETDATA* 0UTPUT={,+1) 

CODE (RECIPE, BGETDATA) 0UTPUT= { ,3) 

END COMPILE-AND-LIST 
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Example 2 

Operation: Same as above. 

Knotms Recipe name is IIST-HODOIE. 

generate list-module; 

ENTER GENERATE SUBCGHKAND. 
scan; 

DEFINE LiST-EODDlE RECIPE-CLASS IS 2 

• SISTEI3-OVIRVIEN' ODTPDT = ($1ISTING, + ) 
SYSTEM-OVERVIEW OOTPUT-(,3) 

STREAM SPRINTER TO PRINTER 

* MODULE ** RGETBATA* 0UTPDT={, + 1) 

CODE {RECIPE, RGETDAT A) OUTPUT^ (,3) 

END LIST- MODULE 
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5.4,2 PROOF Subcommand of GENERATE 


Use the PROOF subcommand to check the existence of inputs and docaids 
and to get an abbre'sriated listing {proof copy) of data referenced in 
data unit., literal or docaid instructions. A syntax check is run first 
and if a syntax error is found, the subcommand is changed to SCAN and 
appropriate error mesages are printed. In either case, the expanded 
recipe is listed. When the *NITH JCL* option is used, the actual jcl to 
be used in document generation is listed. 


SUBCOMMAND 

OPERANDS 

PROOF 

[WITH] JCL 


Example 1 

operation; Initiating the PROOF, 

known; Recipe name is COBOL-COHPILE. 


generate cobol— compile using {recipe, rgetdata) ,clist; 

ENTER GENERATE SUBCOMMAND, 
proof ; 

DEFINE COBOL-COHPILE USING SHODNAME, SPARM RECIPE-CLASS IS 0 
$COBCOMP IHPUT=CODE (RECIPE, RGETDATA) , OPTIONS=CLIST 

567 *:{<:{< LINES FROM INPUT DATA-ONIT 1 FOLLOW, TYPE IS COBOL. 

000010 IDENTIFICATION DIVISION, 

000020 PROGRAM-ID. RGETDATA. 

END COBOL-COMPILE 
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Example 2 

Operation; Same as above, but this time JCl is reguested. 
Known; Same as above. 


generate cobol-compile using (recipe, rgetdata) ,clist; 

ESTES GENESATE SUBCOMMAND, 
proof with jcl ; 

//GENTEST JOB (X03 6 , NASA, 5, 5 ,GH) , HASCAll GEN DOC» 

/*PASSHOED ASAN74 

/^CLASS A 

/*BOUTE PRINT PEINTER3 

DEEINE COBOX-COMPILE USING SMOXNAME, SPARM RECIPE-CLASS IS 0 
SCOBCOMP INPUT=CODE {RECIPE, HGETDATA) ,OPTIONS=CLIST 
//CARDEORM EXEC PGM=DLSTCABD 
//STEPLIB DD DISP=SHS,DSN=TSO.NASA.LOADLIB 

//WRITER DD UNIT=SYSDA,DISP= {NEW, PASS) , DSN=SBT1MPA,SPACE= {THK, 1 0) 
//SYS OUT DD SYS0UT=A 
//READER DD * 

567 LINES FBOK INPOT BATA=UNIT 1 FOLLOW, TYPE IS COBOL 

000010 IDENTIFICATION DIVISION, 

000020 PSOGBAM-IB. RGETDATA. 

//COBOL EXEC C0B0C,PARM=* CLIST' 

//SYSLIB DD DISP=SHE,DSN=T-SO,NASA.;COPYLIB 
END COBOL-COMPILE 


Page 77 






DOHOWIC COHMiND 5EEEBESCE HANOAX ' 
RECIPES AND DCCOHENT GENERATION 


5.4.4 LIST Subcomaiand of GENERATE 


Use the LIST subcoimnaud ±.o get a formatted listing of the L-P~tafale 
named in the GENERATE command. 


SUBCOHMAND 

OPERANDS 



LIST 

Example 1 

operation; 

known: 

Listing the L-P table. 

Recipe name is COHPIIE- ANB-LIST. 



generate compile-and-list; 


ENTER GENERATE SOBCOHNAND 
list; 


506 

LOGICAL NAME 

PHYSICAL DEVICE. 

507 

PRINTER 

SYSODT=A 

507 

PUNCH 

SYSOUT={E,,5 081 1716) 

507 

OBJLIB1 

DIS P=SHB,DSN=TSO.NASA.OBJLIB 

507 

SOORCLIB 

DISP=SHR,DSN=TSO. HAS A. SOORCLIB 

507 

SAVFTLE 

UNIT^SYSD A, DSN=SSTEMPFIX1 ,DISP= (NEW, PASS 
) ,SPACE= (TRK,10) 

507 

DDMPTAPE 

DNIT=TAPE9,VOL=SEE=NASATP,DISP= (NEW, KEEP 
) ,LABEL= (,NL) 


J&/ 
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5,4.3 RUN Subcommand of GENESaTE 


Use the SUN subcommand to produce an actual document. 

NOTE: If a syntax error is found, the subcommand is changed 

to SCAN, If some other error occurs, processing of the recipe 
is halted and an .error message is printed. 


SUBCOMMAND 


OEESaNDS 


BUN 


Example 1 

operation: Initiating the BUN subcommand. 

generate cobol-compile using {recipe,rgetdataiT,clist ; 

ENTER GENERATE SUBCOMMAND. 

run; 
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5.4.5 END SubconuBand of GENEBATE 

Use the END subconnoand to fexminate a GENEEATE session 
SUBCOMMAND OPEBANDS 

iiD 
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6.0 SECURITY 


Security is a subsystem of DOHOUIC. Thi-s subsystem protects the 
documentation system from access by unauthorised users. 


6. 1 TYPES OE SECURITY 


Password security controls which users may SIGNON to documentation 
projects. Every system user must be assigned a passworS and a user 
identification (user- id) , The password specifies which functions and 
users are authorized for a given documentation unit. The user is 
associated with a user description record which contains his name, 
address, department and passwords. The manager must enter the user-id *s 
and passwords befcre others are permitted access tc the documentation 
unit. The password, user id, and BUI must be given when signing on to 
the system. 

Function security controls which executive functions (commands) you are 
authorized to perform for a particular documentation project. The 
functions authorized are associated with each password. The executive 
functions (commands) and their abbreviations are: 


SECURITY C 
MONITOR M 
EDIT E 
GENERATE G 
DEFINE D 
ERASE R 
HEiP H 


Data security controls which data units you may access or update. The 
data access authorizations are in effect when performing the EDIT or 
GENERATE functions. The authorizations are; 

READ-ONLY you may only display data stored in 

the documentation unit. 

NRITE-ONLY you may only enter data into the 

documentation unit. 

UPDATE you may display, enter and change 

data in the documentation unit. 

C.OMHSNT-GNLY — you may display, enter and change 

only the comments in data units of type 
SOURCICODE. 
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HO ACCESS you are uot allowed access to the docanientatioB unit. 

NOTE; the abbreviations for the authorizations are: 


read-only read R 
write-only write H 
coiament-only comment C 
update D 
no access H 


6.2 SECURITY CHECKING AHU HAINTENANCE 


Security operations fall into two categories; security checking and 
security record maintenance. {Only the latter has commands associated 
with it). 

Security checking is performed in conjunction with and internal to 
almost all commands of the documentation system. Password security 
checking is done at SIGHON; function security checking is done when 
major commands such as UEEINE, EDIT, etc, are encountered; and data 
security checking is done before the execution of the EDIT and GENERATE 
DOCUMENTS commands and subcommands which access or change data. These 
checking function are not initiated directly, but are performed after 
you enter a system command. 

The maintenance of the various security records used for checking 
purposes is accomplished by use of the SECURITY command. Security 
maintenance provides the facilities for entering, changing and deleting 
security information. The security maintenance functions are performed 
directly by you as subcommands of the SECURITY command. 


6,3 SECURITY RECORDS 


There are four types of security records; Password., User, Data Default 
and Data Exception. 

A password record contains your password, a list of authorized 
functions, a supervisor password to which you are responsible, user-id, 
monitor class and recipe class, A user-id must exist in the user file 
before it can be added to a password. 

NOTE; each user password is responsible to a supervisor password and 
higher passwords. This hierarchy forms various levels of responsibility 
known collectively as the "password tree*. A password may have no 
greater authority than the password that it reports to. A password’s 
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supervisor may also be called his ancestor. The supervisor password is 
entered in the ‘Reports To* clause. 

User records contain a user identifier, user name, address, department, 
password (s) and city. The data in the user record is used for display 
purposes and not for checking. 

A data default record specifies the default data security authorizations 
for a particular documentation unit. It contains data-type - 
authorization pairs, one pair for each of the following: TEMPLATE, 
RECIPE, EOCAID, TEXT, GRAPHICS, and SOOSCECODE. 

Data exception records specify exceptions to the data default 
authorizations for a particular data item and a particular password. 

They are composed of a password, user-identifier, authorizations (read- 
only, write— only, update, coniment— only and no-access), and change- 
approval. 
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6.4 SECTIEITY Command 


Ose the SECURITY command to add, change, delete and list all or parts of 
the password, user, data default or data exception records of securitj 
records, A session to create or change these records is started by 
entering; 


COHHAND OPESANES 

SECDiliY*^ 


The subcommands of the SECURITY command are; ADD PASSWORD, CHARGE 
PASSWORD, DELETE PASSWORD, LIST PASSWORD, ADD USER, CBAWGE USER, DELETE 
USER, LIST USER, ADD EXCEPTION, CHARGE EXCEPTION, DELETE EXCEPTION, LIST 
EXCEPTION, CHANGE DEFAULT, LIST DEFAULT, HELP and END. 


Example 1 

operation: Entering the SECURITY session, 

known: You are in executive session. 

security; 
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user- id- 1 

a list of eight character identifiers for the users authorized to 
use this password, A user-id must be in the user file before it can 
he added to a password. 

moni tor-class 

a single digit integer which indicates the highest class of monitor 
functions this password is authorized to perform, if any. Zero is 
the default which means none authorized, 

recipe-class 

a single digit integer which indicates the highest class of recipe 
this password is authorized to use when generating documents. 

Recipe class 0 is the default, 

function- 1 

a list of executive functions this password is authorized to 
perform. If a function is not listed, the default is that the 
password is not authorized for that function. Ihe defaults are 
EDIT, 6EHEBATE. ERASE and HELP. 

EXAMPLE 1 

operation: Creating a password record, 

known: Password record .is TEAH1, 

Users are JOE, MIKE, DAN. 

’Report to’ is MANAGER. 

Monitor class is 2- 
Authorization is DEEINE, MONITOR. 

add password teami, reports to manager, users = joe, mike, dan, 
monitor = 2, authorized for define, monitor; 


Example 2 

operation: Creating a password record, 

known: The default is REPORT TO. 

Signed on to password MANAGER. 
User is JOHN. 

Reports to MANAGER. 

Recipe class 1. 

Authorized for DEEINE, 


add password teara2, user john, recipe =1, authorized d; 
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6.4.1 ADD PISSWOED Subccintnand of SECDEITY 


Dse the ADD PASS^JOHD suhcommand to add a record to the password file. 
When adding new passwords, the *Eeports 2o’ must be specified so the 
position in the * password tree* may be located. (See Secnrity Eecords). 
If the 'EEPOBT*S TO’ clause is not specified, the password will report 
to the password that is currently signed on. 


SUBCOHEAND OPEEAEBS 


ADD PASSWOED password, 

[SEPOETS [TO] password-2], 

[DSESS [=] user-id-1, ], 

[MONITOE [=] monitor- cl ass ], 
[EECIPE [=3 recipe-class], 
[ADTHOHIZED [EOE] function- 1 ,... ] 


HOTE: Any of the optional fields (operands) may be added as separate 
subcommands following the ADD PASSWOED isubcomoand. If optional fields 
are not specified, standard system defaults will be used, Eor example: 

ADD PASSWOED 


password 

ESPOETS [TO] pass word- 2 
[DSESS [=] user-id-1,.,.] 

[HONITOE [=] monitor-class] 
[RECIPE [=] recipe-class] 
[ADTHOEIZED [EOE] function-1 ,...]; 


password 

eight character identifier for the password. 


password- 2 

eight character password which this password is responsible in the 
organization of the project. Password-2 must, be different from the 
password." If this field is not specified, the password of the user 
signed on is used. 
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6.4.2 CHANGE PASSNOED Subcommand cf SECURITY 


Use the CHANGE PASSNOED subcommand to change fields in a record in the 
password file. 


SUBCOMMAND 

OPERANDS 

CHANGE PASSWORD 

password, 

[REPOSTS [TO:| password-2], 

[MONITOR [ = ] monitor-class], 
[RECIPE [=] recipe-class], 
[AOTHORIZED [FOE] f unction- 1 ,... ], 
[USERS [ = ] user-id- 1, ... ] 


password 

eight character identifier for the password. 
password-2 

the eight character password to which this password is responsible. 
Password-2 must be different from the password. A password may not 
be changed to report to a password that either directly or 
indirectly reports to itself. 

monitor-class 

single digit integer indicating the highest class of monitor 
functions this password is authorized to perform, if any. 

recip e-class 

single digit integer indicating the highest class of recipe this 
password is authorized to use when generating documents. 

function- 1 

a list of executive functions that this password is authorized to 
perform. 

user-id-1 

eight character identifiers for users authorized for this password. 
Tie user— id must be in the user file before it can be added to a 
password. 
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EXAHPLE 1 

operat-ion: Changing a password record, 

knowns Password record is TEAMI. 

Dser to he added is JOHN, 

Authorisation to he added is GENEEATE. 


change password team!, user = john, authorized for generate; 


Example 2 

operation: Changing a password record, 

known: Password record 1^EAM2- 

Eeports to MANAGEE, 

New reports to LEADES3. 

change password tea m2 reports to*T!iader37 
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6.4.3 LIST PASSKOED SubcOffiBiand of SECUBITY 


Use the LIST PASSWOBD subcommand to list a record in the password file 
for a particular data unit and a specific password. 


SUBCOHI^ND 

OPEEABDS 


LIST PASSTJOBD password, [ ALL ] 

password 

eight character identifier for the password. It will list only that 
password record. 

ALL 

lists the password and all passwords that either 
or indirectly report to it. 

directly 

EXAHPLE 1 

operation: 

known; 

List password entry. 
Password record is TEAMI, 


list password 

team 1 ; 


Example 2 

operation; 

known: 

Listing all passwords in a branch of a 
Password record is TEAH1- 

tree. 

list password 

teami, all; 
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6.4.4 DELETE PASSTIOED SujacommaBd of SECDSITY 

Use the DELETE EASSWOBD suicoToraana to delete a record or record field is 
a password file. 


SDBCOMHAND OPEBAN-DS 


DELETE PASSWOBD password, 

‘ [ADTHOEIZID [BOB] function,..,], 
[MGBITOB [ = ] monitor- cl ass ] , 
[EECIPB [ = ] recipe-class], 

[OSEBS £=] user-id,,..] 


NOTE; if no subfields are specified, a message will be sent asking if 
you want -to delete the entire password record. you may at that time 
respond either YES, in which case the entire password record will be 
deleted or NO, in which case you may then specify which fields within 
the record you want deleted. All fields except users revert to the 
default when deleted. Deleting subfields requires naming the subfield. 


password 

eight character identifier for the password that is to be deleted, 
function 

a list of executive functions to be deleted from this password. 

NOTE; Deleting a function from a pass-word will also delete the 
function from any password that reports to that password (See 
Section 6.3 Security Eecords) . 

monitor-class 

single digit integer indicating the highest class of monitor 
functions this password is authorized to perform, if any. Zero is 
the default and means no’ authorization. 

red pe -class 

single digit integer indicating the highest class of recipe this 
password is authorized to use when generating documents, Eecipe 
class 0 is the default. 

NOTE; Lowering the recipe cr monitor class of a password also 
lowers the recipe or monitor class of any password that reports to 
-that password (See Section 6.3 Security Records). 
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user- id 

a list of eight character user id*s to be deleted from this 
password. 


EXAMPLE 1 

operation: Deleting a passiford record, 

known: Password record is TEAM1. 

delete password team1; 


System will respond by asking whether you want the entire password 
record and its descendants deleted. You should respond by entering: 


yes; 


Example 2 

operation: Deleting a user and authorization in a password 

record. 

kncwn: Password record is ITEAM1. 

Dser is JOHN. 

Authorized for GENERATE. 


delete password teami, user = john, authorized for generate; 


Example 3 

operation: Same as above# but you enter: 


delete password teami; 


The system will respond by asking whether you wish to have the 
record deleted. You should respond: 


no user = John# authorized for generate; 
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6.4.5 ADD USER Sobcoraraand of SECDEITY 


Dse the ADD DSEE subcominand to add a record to the user file. 


SnBCOKEAED OPEBANDS 


ADD USEE user— id, 

[CITY [ = ] aser-city-rarae ], 

[NAME [=] user-name], 

[STREET [=] user— street-address ], 
[DEPT [=3 user-departmeut-name] 


user-id 

the eight, character identifier for the user to be added, 
user- name 

a 20 character string for the user*s name, 
user- street-addr ess 

a 20 character string for the user’s street address, 
user-city— state— zip 

a 20 character string for the city, state and zip code, if any. 
user— department- name 

a 10 character name for the user's department. 

NOTE: Passwords are automatically updated in the user file when a user 

is added or deleted from a password. 


EXAMPLE 1 

operation: Creating a user record, 

known: User— id is MANAGER. 

Name is SMITH. 

City is DALLAS. 
Department is BPC. 


add user manager, name = smith, city = dallas, department = dpc; 
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6,4.6 CHANGE OSEH Su bcotnmana of SECUHITy 


Use -fhe CHANGE USER subcojamand to change a record in the user file. 


SOBCOHMAND OPERANUS 


CHANGE USEE user-id, 

[CITY [=] user— city-name ], 

[NAME [=] user-name], 

[STREET [— ] user— street-address ], 
[DEPT [=3 user-department-name] 


user- id 

the eight character identifier for the user to be changed, 
user-city-name 

a 20 character string for the aser*s city which replaces the old 
city name. 

user-na me 

indicates a 20 character string for the user’s name, 
user— street— address 

indicates a 20 character string for the street address of the user, 
user-department- name 

indicates a 20 character name for the user’s department. 


EXAMPLE 1 

operation; Changing a user record, 

known: User record manager. 

Street is MAINDRAG, 

City is SNYDER. 


change user manager, street = maindxag, city = snyder; 
city = snyder: 
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6.4.7 LIST USEE Su bcoifunan 3 of SECUEITY 


Use the LISI USEB subcommand -when you want a list of user records, 
or parts of the user record may be listed for inspection. 


SUBCOMMAND 

OPEEANDS 

LIST OSES 

user-id. 


tPASSHOBD] £ALL] 


user-id 

the eight character identifier for the user to be listed, 
PASSAGED 

a list of eight character passwords for which this user is 
authorized. These passwords must already exist in the password 
file- 

ALL 

’ indicates the entire list of passwords for a user. 

NOTE: Only the master password may list the passwords of a user. 


EXAMPLE 1 

operation: Listing a user record without the passwords, 

known: User record manager. 

list user manager ; 


Example 2 

operation: Listing passwords within a user record, 

known: User record manager. 

list user manager, passwords; 


)1U 


All 
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6.4.8 DELETE DSEE Subcomiaana of SECDEITZ 


Use t.he DELETE USEE subcofflffland to delete a record la the user file. 


SUBCOMMAND OPEBANDS 


DELETE USER user-id, 

[CITY] [NAME] [STREET] [DEPT] 


user- id 

the eight character identifier for the user to be deleted, 

CITY 


indicates 

a 

20 

character 

string 

for 

the 

user's 

city. 

NAME 

in dicates 

a 

20 

character 

string 

for 

the 

user's 

Eame. 

STREET 

indicates 

a 

20 

character 

string 

for 

the 

user's 

street address. 

DEPT 

indicates 

a 

20 

characte r 

string 

for 

the 

user *s 

department. 


EXAMPLE 1 

operation; Delete user record, 

known: User record is MANAGER and delete CITY, 


delete user manager, city; 


Example 2 

operation: Deleting a name in the user record, 

known: User record manager, 

Dser wants to delete name, but types 
'DELETE USER MANAGER;'. 

The system will then ask you if you want to delete the entire record. 
You will respond by entering: 


no, name; 
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Example 3 

operation: Delete manager in user record, 

known: User record manager. 


delete user manager; 


System will ask if you want to delete entire record. You 
respond by entering; 


yes; 


NOTE; A user cannot be deleted if it contains a password. 



Page 96 



DOMONIC COHMAND RETEHENCE aflMUflL 
SECURITY 


6.4.9 ADD EXCEPTION Subcommand of SECURITY 


Use the ADD EXCEPTION subccmmand to create an entry in the exception 
file. You may add, cahnge or delete any passwords from the exception 
records that you haT/e control of. 


SUBCOEEAND OPERANDS 


ADD EXCEPTION D ATA-UHIT-N AHE PASSWORD [=] password, . 

[AUTHORIZED [POE] da ta-authoxization], 
CHG-APPE07AL [=] YES 

Y 

NO 

N 


NOTE: If you do not specify any operands for ' authorization, the default 

is UPDATE-ONIY and CHG- APPROVAL is no. 


password 

eight character identifier for the password, 
d a ta- an thor izat ion 

type of access to data allowed for this password, (For 
authorizations see ’Types of Security*) 

CHG-APPROVAL 

written authorization to change a data- unit. 


Example 1 

operation: Adding an exception to record SECURITY. DATA, 

known; Password is TEAMI. 

Authorization is UPDATE, 

add exception secur ity.da ta password is teami, authorized for update; 


Example 2 

operation: Adding two exceptions to record SECURITY. DATA, 

known: Password TEAH2 has authorization GOHMENT. 

Password TEAM3 has authorization EFAB-ONLY, 
Change-approTal should he changed to YES. 
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add exce'pt.ion securi ty. data, password teain2, authorization comment, 
password teams, authorization read-only, chg-approval yesj 
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6.5,10 CHANGE EXCEPTION Subcciiimand Of SECUEITI 


Use the CHANGE EXCEPTION subcommand to create or change a subentry in 
the exception file. 


SUBCOMMAND OPERANDS 

CHANGi"¥xC^Tf 0 N FATA"jD~iASsioBD~f^~passw or 3,7777 

[AOTHOBIZED [POE] data authorization], 
CHG-APPEOVAL [=] YES 

Y 

HO 

N 


password 

eight character identifier for the password, 
data-a uthox iza tio n 

type of access to data allowed for this password, 
{Por authorizations see Section 6.1.) 

CHG-APPEOVAL 

written authorization to change a data-unit. 


Example. 1 

operation; Changing an authorization, 

knowni One exception for record SECURITY. DATA is password 

TEAM3. 

Authorization is READ-ONLY. 

Change the authorization to UPDATE. 

change exception security .data password team3 authorized for update 
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6.5.11 LIST EXCEPTION Suiccnnnand of SECURITY 


Use the LIST EXCEPTION subcommand to get a listing of an exception file 
or its subfield. 


SOBCOliHAND OPERANDS 

LIST EXCEPTION data-unit-name , 

[PASSWORD [=] password], 
[CHG-APPBOVAL] 


NOTE; If you do not specify any operands the default is all. 
data-unit-name 

the name of the data elements, templates, recipes or docaids 
you want listed, 
password 

eight character identifier for the password, 

CHG- APPROVAL 

written authorization to change a data-unit. 


Example 1 

operation; Listing the exceptions for the data unit SECURITY. DATA, 
list exception security, data 


Example 2 

operation; Listing exceptions for data unit SECURITY, DATA, 
known; Passwords are TEAE3, TEA«2, and TEAM1. 


list exception security. data, passwords = tean3, team2, tearal; 


Example 3 

operation; listing the exception change-approval for SECURITY. DATA. 


list exception security. data chg-approval; 
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6.5.12 DELETE EXCIJPTICN Sub com in and of SECURITY 

Use the DELETE EXCEPTION subcommaija tc delete a subentry in an 
exception file. 


SUBCOMMAND OPERANDS 


DELETE EXCEPTION [ DATA-UNIT-NAME PASSWORD [ = ] passnord,. . . 


NOTE: If no subentries are entered, a message will be sent asking if 

jou want to delete the entire exception file. You may at that time 
respond either YES, in which case the entire exception file will be 
deleted or NO, in which case you may then specify which subentries you 
want deleted. 


password 

eight character identifier for the password. 


Example 1 

operation: Deleting a subentcy." 

known: Deleting frcin the exception file named SECURITY, DATA, the 

passwords TEAH1 and 1EAH2. 


delete exception security . data passwords teami teaic2; 


Example 2 

operation: Deleting the entire exception record for the data unit 

SECURITY. DATA. 

You enter: 


delete exception security .data; 


The system will then ask whether the entire record should be deleted. 
You respond: 


yes; 
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6.5.13 CHANGE DEFAUXT Suicommand cf SECORITY 


Use the CHANGE DEFAULT subcommand to change the authorization 
in the default file. 


SUBCOMHAND GEEEANDS 

CHANGE "'dee AULT DAH-uili^YiE~[^''data "authorizatl^T 

da ta— element-type r 
CHG-APPSOVAL £=3 YES 

Y 

NO 

N 


data authorization 

type of access to data alloyed for this password. 

(For authorizations see *Types of Security*). 

data-element-type 

the type of information of the data-element: TEXT, GRAPHICS or 
SOUBCECODE, 

CHG-APPROVAL 

written authorization to change a data-unit.. 


Example 1 

operation: Changing default for a system. 

JcQQwn: Recipe is READ-ONLY, Text is COHMENT-GNLY and 

you want to change both to UPDATE. 

change default recipe = update, text = update; 


Example 2 

operation; Changing default for a system. 

known: Required Change-approval is NO and you want to change it 

to YES, 

change default chg-approval = yes; 
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6.5.14 LIST DEEAUET S uttcominand of SECUSITY 

Use the LIST DEFADLT subcommajid to get a listing of the default file 
* 

sdbcoHmand opeeands 

^list^uefIult 

documentation-unit— id a 30 character naiae for the documentation unit 
Example 1 

operation: listing a default file, 

list default; 
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6.5.15 EHD Subcommand of SECUEITY 

Use the END subcommand to terminate the security session. 

SUBCOMHAND ' OpiiANDS 

END 


Example 1 

operation: Terminating a SECUEITY session. 
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7.0 SIGNOFE Commana 

Use the SXGNOFF com maud to end a session with the system. 


The SIGNOFE command removes yon from active status in the varions 
internal system tables, e.g. Templates, Security, etc. A message is 
printed at your terminal or on your printed listing indicating the 
elapsed time of the session. 


COEHAND 


SIGITOFF 


OPERANDS 


EXAMPLE 1 

operation: Ending a terminal session. 


signotf 

SIGNOFF COMPLETE ** ELAPSED TIME - 1 HOUR 20 MIN 15 SEC 
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8.0 SIGNON Command 


Use the SIGNON command to initiate use of or gain entry to the system. 
Successful completion of the SIGNON command connects you to the system. 
When using the SIGNON command you should give your user-id, password and 
documentation unit identifier. If any of these items are omitted in the 
interactive mode, you -will be prompted. In the batch SIGNON, all items 
must be supplied. SIGNON will respond with the time and date if the 
three items successfully pass the security test. If a fault is 
detected, an error message is returned and you are asked to enter SIGNON 
again. 

NOTE: possible error messages are: 

MAXIMUM USERS SIGNED ON ** PLEASE TE2 LATER 
INfALID PASSWORD ** PLEASE SIGNON AGAIN 
NO RECORD OE USER-ID POUND ** PLEASE SIGNON AGAIN 
DOCUMENTATION UNIT DOES NOT EXIST ** PLEASE SIGNON AGAIN 
USEE IS NOT VALID EOR THIS PASSWORD ** PLEASE SIGNON AGAIN 
DOC UNIT NOT VALID EOR THIS PASSWORD PLEASE SIGNON AGAIN 


COMMAND OPERANDS 


SIGNON USEE [=] user-id 

PASSWORD [=] password 

DOCUMENTATION UNIT [=] documentation- unit- id 
DUI 


user-id 

an eight character string that identifies the user. 


password 

an eight character string. that identifies the password that you are 
authorized to use. 


documentation— unit- id 

a character string (maximum 30 characters in 
a documentation unit. 


length) that identifies 
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EXAMPLE 1 

operation; Initiate a session, 

known; Dser-id is AESEYEN. 

Password is B7. 

Documentation unit is NASADOC. 


signon user = arse.ven password = r7 dui = nasadocj 


EXAMPLE 2 

operation; Initiate a session, 

known; User-id is ABSEYEN- 

Password is R7. 

Documentation unit is NASADOC. 


signon; 

• ENTER USER IDENTIFICATION 
arse ven; 

ENTER PASSWORD 
r7; 

ENTER DOCUMENTATION UNIT IDENTIFIES 
nasadoc; 
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9.0 SYSTEM command 


flse the SYSTEM command to enter the system mode. This allows you to 
execute the SYSTEM subcommands. THE subcommands of SYSTEM allow you to 
attach or detach common data sets from the system, initiate or purge 
documentation nnits, and change a documentation units allocated data 
sets. The SYSTEM command is a restricted ccmmand. 


COMMA HD 


OPERfiNDS 


SYSTEM 
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9. 1 DUBGE SubcoiDHiaBd of SYSTEM 


Use the PURGE subcommand to remove a documentation unit from the system. 
If the documentation unit is located on common data sets, the storage 
used on those data sets is returned to the lists of available storage. 

If a documentation unit is located on private data sets, you will be 
prompted for a ’YES’ or *H0* response to indicate if the storage should 
be freed- 


COMHAND OPERANDS 


PURGE [DUI [=]] name-1 

fVERSIGN [=]] number 


name-1 

a 1 to 30 character documentation unit identifier. 


number 

a 2 or 3 digit number of the from d.d or dd.d that indicates the 
version and level of the documentation unit. 


Example 1 

operation; Purging a documentation unit located on common 
data sets. 

known; Documentation unit is DOC-UNIT- 1- 

VERSION 2.2 exists. 


purge dui = doc-unit- 1 version 2.2; 


Example 2 

operation: Purging a documentation unit located on common 

data sets. 

known: {Same as example 1) . 

purge dui doc-unit- 1 version 2.2; 


Example 3 
Operation: 

known: 


Purging a documentation unit located on private 
data sets. 

Doc- unit is DOC- UNIT- 2. 

Version is 1.0, 



Page 1 09 




DOaOHIC COMAND BEJIEENCE BAHUSE 
SI STEM, COMMAND 


purge aui=aoc-unit-2 version=1 . 0 ; 

BOG UNIT ON PBIVaTE DATASETS. 

EBTEH »YES’ TO FREE D STASETS STORAGE. 

yes; 


Page 110 





DOaONIC COHHAND EaiEEENCE SAKOAL 
SYSTEM COMHAED 


9.2 ATTACH Subcommand of SYSTEH 


Use the ATTACH subcommand to make a ccmmon data set known to the system. 
One to three data sets may be entered. 


SUBCOMHAED 


OEEHANDS 


attach [DATA-SET] ds-name-1 ON [VOIDME] vcl-name-1 

[DATA-SET] ds— narae-2 ON [VOLUME] ■vol-name-2. 


i 


ds-name-1 ,ds—name-2 

a 1 to 8 character identifier that conforms to the rules for 
IBM data set names- 

vol— name- 1 , vol-name-2 

a 1 to 6 character identifier that conforms to the rules 
for IBM volume names. 


Example 1 

operation: Attaching 1 to 3 common data sets to the system, 

known: Volumes DOMONIC1 and DOHONIC2 are online. 

Data-sets C0MMGN1, CGMM0N2, C0KH0N3, C0MM0N4 and COMMONS 
have been allocated and initialized. 

COMHON1, COHMON4 and COMMONS are on DOMONICl . 

C0MH0N2 and COMMONS are on DOHONIC2. 


attach data-set commoni on volume domonici; 

attach common2 on domonic2, commons on domonic2; 

attach data-set common4 on domonici, commons on volume domonici; 
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9.3 DETACH Subcommand of SYSTEM 


Use the DETACH subcommand to remove a common data set from the system. 
If the system finds that a documentation unit currently has storage 
allocated to it on the data set, then the data set will not be detached. 


SUBCOMMAND 


OFERANDS 


DETACH tI5ATA-SET3 ds-name-1 ON [VOLUME] vol-*name-1 

[DATA-SET] ds-name-2 ON [VOLUME] vol-name-2. 


ds-name-1 ,ds-na me- 2 

a one to eight character identifier that conforms to the rules 
for IBM data set names. 

vol-name-1 , vol-name-2 

a one to six character identifier that conforms to the rules 
for IBM volume names. 


Example 1 

operation: Detaching 1 to 3 ccmraon data sets from the system, 

known: Volumes DOMONICI and DOMONIC2 are online. 

Data sets COHMCNI and COMMON4 are located on DOMONICI. 
Data sets C0MMQN2, C0HMCN3 and COMMONS are located 
on D0M0NIC2. 


detach data-set commonl on volume dcmcnicl; 

detach common2 on domcnic2, common3 on domonic2; 

detach data-set ccmmon4 on demonic 1, commons on volume doraonic2; 
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9.4 INITIATE Subcommand of SYSTEM 


Ose the INITIATE subcommand to initiate a nev documentation unit. To 
start tJie initiation process, the INITIATE subcommand is entered with 
the new documentation unit name and version number. If the 
documentation unit name is unique, the user will be prompted for the 
following information: HASTE E EISSROED, MASTER OSER ID and DATA SET 
ALLOCATION PARAMETEBS. 

The MASTER PASSWORD and the MASTER USER ID must be 1 to 8 characters in 
length. The first character must be alphabetic and the remaining alpha- 
nuraberic. 

If ANY is given as the response to the request for data sets, the system 
will allocate a data set from the ccmiton pool. If private data sets are 
d-esired, they must be named explicitly using the second response format. 
A maximum of nine data sets may be specified. 


SUBCOMMAND OPERANDS 


INITIATE • [DUI £=]] name- 1 

[VERSION [=]] number; 


If the documentation unit name is unique, the user will be prompted. 
The format for the prompt responses are: 


ENTER MASTER PASSNOBD name-2; 

ENTER MASTER USER ID name-3; 

ENTER DATA-SET ALLOCATION ANY; 

[DATA-SET] ds-name-1 ON [VOLUME] vol- name-1 
[DATA— SET] ds-name-2 ON [VOLUME] voi-name-2 


name-1 

a 1 to 30 character documentation unit identifier, 
number 

a 2 or 3 digit number of the form d.d or dd.d that indicates the 
version and level of the specified documentation unit, 

name-2 

a 1 to 8 character password that will become the master password 
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for tKe Dew documentation unit. 
name-3 

a 1 to 8 character user id that will tecome the master user id 
for the new documentation unit. 

ds-name-1 

a 1 to 8 character identifier that conforms to the rules for 
data set names. 

VO 1-name- 1 

a 1 to 6 character identifier that conforms to the rules for 
volume serial numbers. 

ds-name-2 

a 1 to 8 character identifier that conforms to the rules for 
data set names, 

vol— name-2 

a 1 to 8 character ident if ier • that conforms to the rules for 
volume serial numbers. 


Example 1 

operation: Initiating a documentation unit, 

known: Documentation unit is DOC-ONlT-1, 

VEBSION 1.0 does not exist. 

Desired user id is MANAGER and the desired 
master password is DOMES. 

The manager of DOC-UNIT-1 wants the documentation 
unit to exist on data sets SYSDUI1 and SYSDDI2 
which are located on volume S^SDOC. 


initiate dui = doc-unit-1 version = 1.0; 

ENTER MASTER PASSROED 

jones; 

ENTER MASTER USER ID 
manager; 

ENTER DATl-SET ALLOCATION 

sysduil on sysdoc sysdui2 on sysdoc; 
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Example 2 

operation; Initiating a docnmentation unit, 

known; Documentation unit is DOC-UNIT-1. 

VERSION 1.0 does not exist. 

The desired user id is MANAGES and the desired 
master password is JONES. 

The manager of DOC— UNIT-1 wants the documentation unit 
exist on data sets SYSD0I1 and SYSD0I2 which are 
located on SYSDOC- 


initiate dui doc- unit-1 version 1.0; 

ENTER MASTEB PASSNOBD 

jones; 

ENTER MASTER USEE ID 
manager; 

ENTER DATA-SET ALLOCATION 

sysdui 1 on sysdoc sysdui2 on sysdoc 

CONTINUE 


Example 3 

operation; Initiating a documentaticn unit, 

known: iSame as example 1) 


initiate dui doc-unit— 1 version 1.0; 

ENTEE MASTER PASSNOSD 

jones; 

ENTER MASTER USER ID 
manager-; 

ENTER DATA-SET ALLOCATION 
data-set sysduil on volume sysdoc 
CONTINUE 

data-set sysdui2 on sysdoc 
CONTINUE 


Example 4 

operation: Initiating a documentation unit. 

known: Same as example 1 except four data sets are 

to be allocated: SYSDU11 and SYSDUI2 on volume SYSDOC, 
SYSDUI3 on volume SYSNS1 and SYSDUI4 on volume SYSNS2. 
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Initiate doc- unit— 1 1,0; 

ENTER HASTES PASSWOBD 
jones; 

ENTEfi WASTES OSES ID 
manager; 

ENTER DATA-SET ALLOCATION 
data-set sysduil on sysdoc 
CONTINOE 

sysdui2 on sysdoc sysduiS on sysnsi 
CONTINOE 

sysdui4 on volume sysns2; 


Example 5 

operation; Initiating a documentation unit, 

known;' '{Same as example 1, except common data sets are to be used). 


initiate doc- unit- 1 1.0; 
ENTER WASTER BASSNOSD 
gones; 

ENTER HASTES OSES ID 
manager; 

ENTER DATA-SET ALLOCATION; 
any; 
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9.5 ALXOCATE Subcommand of SYSIEM 


Dsc the ALLOCATE subcommand to attach a new data set to a documentation 
unit that was initiated using private data sets. If a documentation 
unit was initiated using coamon data sets <fche ANY option of the 
INITIATE subcommand) , the system will automatically allocate other 
common data sets to the documentation unit as they are needed. Data 
sets should be on line and formatted before bring allocated to a 
documentation unit. 


SUBCOMflAND OPERANDS 


ALLOCATE [DATA-SET] ds— name-1 ON [VOLDHS] voi-name— 1 

TO doc-unit-id 7ERSI0N number 


ds— name-1 

a 1 ho 8 character identifier that conforms ho the rules 
for data set names. 

vol-narae-1 

a 1 to 6 character identifier that conforms to the rules 
for volume serial numbers. 

doc-unit-id 

a 1 to 30 character identifier that is the name of an existing 
documentation unit. 

number 

a 2 or 3 digit number of the form d-d or dd.d that indicates the 
version and level of the specified doc u men tail on unit- 


Example 1 

operation: Allocating a data set. 

known; Documentat-ion unit is DOC-DNIT- 1. 

VERSION 1.1 exists. 

Data set SYSDUI13 ON VOLUME SYSDOC is online and 
formatted. 


allocate data-set sysdui13 on volume sysdoc to doc-unit-1 version 1.1; 


Q 
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Example 2 

operation: allocating a data set. 

known; Documentation unit is DOC-DNIT-1. 

VEBSlOH 1,1 exists. 

Data set SYSDDI13 OE VOLDHE SYSDOC is online and 
formatted. 


allocate sysdui13 on sysdoc to dcc-unit-1 version 1.1; 
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9-6 DEALLOCATE Subcommand of SYSTEM 


Use t-he DEALLOCATE subcommand to remove a previously allocated data set 
from a documentation unit. 

If the documentation unit has any storage allocated to it on the data 
set, the data set will not be deallocated. 


SUBCOMMAND OPEBAKDS 

M ALLOCATE fo ATl^iETl”*ds^ame^”oN~[ToLUHi~]~voI^^me^ 
EECH doc-unit-id VEESION number 


ds-name-1 

a one to eight character identifier that conforms to the rules fox 
data-set- names. 

vol— name- 1 

a one to six character identifer that conforms to the rules 
doc-unit-id 

a 1 to 30 character identifier that is the name of an existing 
documentation unit. 

number 

a 2 or 3 digit number of the form d.d or dd.d that indicates the 
version and level of the specified documentation unit. 


EXAMPLE 1 

operation: Deallocating a data set. 

hnown: Documentation unit is DOC-UNIT-1. 

VEESION 1.0 exists 

Data set SYSDUI21 CN VOLUME SYSDOC is allocated to 
DOC-UNIT-1 

deallocate data— set sysout21 on volume sysdoc from doc-unit-1 version I-O 5 
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Example 2 

operation: 

3ciiC¥n: 


Deallocating a data set. 

Documentation unit is DOC-UKJT-1, 

YEESION 1,0 exists 

Data set SYSDDI21 013 VOLUME SYSDOC is allocated to 
DOC-UNIT-1 


deallocate . sysdui2 1 on sysdoc ixora doc-unit— 1 version 1.0; 
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Short 

Name 

tT 

T2 


T3 

T4 

T5 

T6 

T7 


T8 

T9 

T10 

T1 1 

T12 

T13 

T14 

T15 


Data 

SYSTii^OVEEVlii7*”TiET7''iAX~1 0,000~LliES, '/*ioRD 
DESCSIPTION OF THE SYSTEM*/; 

SYSTEM-BLOCK-DIAGBAM, GIAPHICS, MAX 25 PAGES, /^SYSTEM 
FLCWCHAETS*/; 

SUBSYSTEMS, MAX 20 TIMES ID=SUBSYSTEE-NAME; 

SUBSYSTEM-NAME IN T3, TEXT, MAX 30 CHARACTERS; 

SUBSYSTEM-MODDIES IN T3, MAX 500 TIMES ID=MOD OLE-TITLE; 

MODULE-TITLE IN T5, TEXT, MAX 30 CHARACTERS; 

MODULE-CODE IN T5 , SGURCECODE=COBOL PL/1 ASSEMBLER, 

MAX 100 TIMES, /*SIROCTORED PROGRAMMING IS TO BE , 
USED IN ALL PROGRAMS*/; 

MODULE-INPUTS IN T5, MAX 10 TIMES ID,=I-NAHE; 

I- NAME IN T8, TEXT, MAX 8 CHARACTERS; 

I- DESCRIPTION IN T8 ; 

MODULE-OUTPUTS IN 15, MAX 10 TIMES ID=0-NAME; 

0-NAME IN T10, TEXT, MAX 8 CHARACTERS; 

O- DESCRIPTION IN T10, TEXT; 

SUBSYSTEM-ABSTRACT IN T3 , TEXT, MIN 3 PAGES; 
MODULE-ABSTRACT IN T5, TEXT, EXACTLY 2 PAGES; 


FIGURE 5 SOURCE TEMPLATE LISTING FECM THE EDITOR 
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T1 

T2 

T3 

T4 

T14 

T5 

T6 

T15 

T7 

T8 

T9 

T10 

T1 1 

T12 

T13 


SISTEH-OVEEVIEW 

SySTEM-BXOCK-DIAGBAM 

SUBSYSTEMS 


SUBSYSTEM-NAME 

SDBSISTEM-ABSTBACT 

SUBSYSTEM-MODULES 

MODULE- TITLE 
MODOLE-ABSTHACT 
MODULE-CODE 
MODULE- INPUTS 

I-RAME 

I-DESCHTPTION 

MODULE-OUTPUTS 

0-HAME 

O-DESCBIPTION 


EIGUBE 6 BOUND TEMPLATE LISTING EBCM DEFINE DATA 
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10.0 


TEMELATES AO DATA DEEIKITIONS 


Templates specify basic elements of information required to develop and 
document a programing project. you can, by means of a template, name 
the data elements to be collected, specify their characteristics and 
define their hierarchical relationships to each other. The data 
characteristics include, a data element’s type- JTEXT, GRAPHICS, 
SOURCECOBE) , its length and the number of times it can be repeated. The 
hierarchical relationship determines lihere it is placed in a tree 
structure corresponding to the template. 


10,1 TYPES QF TEMPLATES 


There are two types of templates^ source templates and bound templates. 
Source templates are in character string form and are stored in the 
template library for the documentation unit. A bound template is 
created from a source template. It has a fixed internal structure -which 
facilitates the storage and retrieval of data elements. There is only 
one bound template for each documentation unit. 


10.2 SOURCE TEMPLATES 


A source template consists of a sequence of data definitions. The 
source template is entered through .the editor in the normal line by line 
fa shion. 

The editor handles the source template just as if it were lines of text. 
Each line may be changed, listed, deleted, etc,., using the full range of 
EDIT subcommands. The editor does not interpret the template data 
definitions. Hhen the edit session is finished the source template is 
saved in the template library of the documentation unit. Any number of 
source templates can be stored in the template library. 


10,3 TEMPLATE STRUCTDHE 


The template data definition language is designed so templates can 
impose a hierarchical structure on the data elements in a documentation 
unit. There are as a result two types of data definitions, those which 
define group levels {hierarchy) and those which define data elements. 

A group level definition is one which has other definitions subordinate 
to it. 


^3 
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The data element definition is one isfhich does not have any other 
definitions subordinate to it. Only data elements definitions -will have 
data physically associated with them. 

The highest template level is the template itself and is defined to be 
level zero, {See Figure 6 in this section.) 

In addition to a template having hierarchy it may also have depth. The 
depths is achieved by allowing data definitions to occur multiple times. 
The data defintion can be replicated, each replication being uniquely 
identified. The number of times a data definition can be repeated can 
be controlled. The repetition is created when the actual data is 
entered and stored and these replications are called repeated occurrence 
groups. (See Figure 5 in this section, } 


10,4 DATA DEFINITION lANGDAGE 


Templates contain definitions of data elements. These data definitions 
describe what data is to be entered for project development and 
documentation. The template is normally designed by the project manager 
before development begins. The data definition language is used to 
write source templates, 

A data definition {a statement in the data definition language) consists 
of a short and a long name for the definition, a list of attributes 
{repetition factor, units' of measure, data element type) , designation of 
position in a hier-archy and an explanation of the data definition. Each 
data definition in a source template starts with a short name and ends 
with a semicolon (;). The data definition format is: 


short-name long-name [IN father- short- name ] [ data-element-ty pe ] 
[ units- of- measure] [repetition factor] [/^^‘explanation*/]; 


short- name 

a *T* concatenated with a five-digit integer less than 32759. 
Valid short— names range from T1 to T3275S. TO is a system 
assigned short-name and always refers to the top level. It 
cannot be assigned to a data definition in the template. 

long-name 

the descriptive name of the data definition. It is a character 
string of length 1 to 30. The first character must be 
alphabetic, characters 2-3 0 may be alphabetic characters, 
digits, dashes or underscores. Short- names are not valid 
long-names. 
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f a t h e r— sho r t.- Q a m e 

the short-name of the data definition in the template to which 
this data definition is subordinate {at the next lowest level 
in the hierarchy) . If ’IN* is not specified the entry is 
assumed to be on the main level ^hich is referred to 
as TO, Eight levels of subordination are permitted. 

data- element- type 

the type of data element this data definition defines. 
Data-eleraent-type may be either TEJTj GEAPBICS, or SOUECECODE. 
The format for data— element-type is: 


SIXT 

SOERCiCODE = 
GRAPHICS 


ANI 

lang-1 lang-2.... 


where lang-1 lang-2... are separated by blanks and are chosen 
from COBOL, EOETBAN, ASH, PX/1. The default for 
data— element— type is TEXT. 

units- of- measure 

specifies limits on the sitze of the data element, if any. 

The format for the units— of -measure is: 


MIN 

MAX integer 

EXACTLY 

MANY 


CHA RACT ERS 


ROEDS 

LINES. 

PAGES 


where MAX, MIN, EXACTLY, MANY {sizetest) and the integer 
{between 1 and 32759 inclusive) limit the size of the data 
element and CHARACTERS, HOEDS, LIKES, PAGES give the 
units- of- measure (textmeasure) . One word is 10 characters, 
one line is 60 characters and one page is 50 lines. 

Defaults: 

1. If no units-of-measure is given, the default is 
MANY CHARACTERS, 

2, If the sizetest is given and textmeasure is not, the 
default for textmeasure is CHARACTERS. 
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3. If sizetest is not given and textraeasure is given, tte 
default for sizetest is EXACILI. 

The unit.s-of-measnre determines the size of the stored data 
element and in no way affects the size or format of. any output, 

repetition- factor 

specifies how may times a data element or group of 
data elements may occur. The format for the 
repetition-factor is: 


MAX 

MIN 

EXACTIY integer TIMES ID = id-def-name 

HAMY 


where MAX, MIN, EXACTLY, MANY (sizetest) and the integer 
(between ^ and 32759 inclusive) limit the number of times 
a data element or group of 3ata elements may ccdur. 

The id-def-name is the name (short or long) of hhe data 
definition whose value uniquely identifies a particular 
occurrence of a data element. There must he at least one 
data element assocaited with each id-def-name in hhe 
template. TIME and the ID = phrase must always be given 
in the re petition- factor. 

Defaults: 

1. If sizetest is given and the integer is not, the 
default is MANY TIMES. 

2. If sizetest is not given and the integer is given, 
the default is EXACTLY integer TIMES. 

3. Sizetest MANY overrides any integer given, 
explanation 

any description or instruction about the data to be entered for 
the definition. Any EBCDIC character string is allowed. 

Data definitions for group levels may contain only the short-name, long- 
name, IN phrase and repetition-factor parts of the generalized- da ta 
definition. Data definitions for data elements may contain all parts of 
the generalized data definition. The only parts which are required for 
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a definition are the short-name and the long-name; all others will take 
default values. 


10.5 BODND TEEDLATES 


Once you are satisfied with the data definition {as written in a source 
template) , it can he translated into the hound template for the 
documentation unit. The hound template consists of a number of internal 
system tables which determine the structure and the attributes of the 
data in the documentation unit. It also contains pointers to maps which 
tell where data is stored. The operation of producing these tables is 
known as ’binding the template’. 

The template binding process creates a bound template from a source 
template. Prior to binding, no data elements may be entered into a 
documentation unif. 

Template binding is one of the main functions of the DEFINE DATA 
command. The DEFINE DATA command provides access to the subcommands 
used to bind a templates or to make additions or corrections fo a bound 
template. After you enter the DEFINE DATA command, you may enter the 
template manipulating commands for which you are authorized. 
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io.6 DEFINE DATA COlBIDand 


The DEFINE DATA command puts you in the node to hind a template for a 
docamentation unit ox to mate additions or ‘ corrections to a hound 
template. 


COHEAND 


DEFINE DATA 


OPERANDS 


Once you enter DEFINE DATA, you may enter the template manipulating 
subcommands for which you are authorized. The subccmmands of DEFINE 
DATA are: 

TEST GRANGE 

SAVE HELP 

DELETE LIST 

ADD END 
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10*6.1 TEST Subcommand of DEEIKE BATA {Template Binding) 

Template binding scans your source template for errors. <A source 
template is a template which is entered through the editor). 

___i „ 

SOBCOHHAND “ OPESANDS 

TEST USING template— same 


template -name 

a source template which was entered through the editor. 


EXAMPLE 1 

operation: Trial binding the template 

known; Template-name is TEMPLATE-MAS A-SISTEM. 


test using template-nasa— system; 


MOTE: After binding, this command can no longer be used for this 
documentation unit. 
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10.6.2 SA7E' Subcommand of CEFIHE DATA {Template Binding) 

Use the SAVE subcommand when you have had an error— free TEST and want to 
produce a bound template. 


SOBCOHMAND 

OPERANDS 

SAVE USING 

template— name 


template -name 

a source template which was input to the system through the editor. 


EXAMPLE 1 

operation; Producing the template. 

known; Template- name is TEMPLATE-NASA-SYSTEH. 


save using template-nasa- system; 


NOTE; After template binding, this command can no longer be used for 
this documentation unit. 
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10,6*3 DEIETE Subcommand of DEEINE DATA 


Use the DELETE .subcommand fo delete a data definificn in the bound 
template. 


1 


SUBCOMMAND 

OPERANDS 



DELETE 

data-def-na me, 

[IN father— short-name ] 




data— def- name 

the 3 0 character name of the data definition to be deleted. (For 
rules in creating a data— definition- name see Section 10.4.) 

fa ther-shor t- name 

the short name of the data definition to which data-def inition -name 
to be deleted is directly subordinate. 


EXAMPLE 1 

operation: Deleting an entry in the template, 

known: Data-def-name is MODDLE-ABSTEACT. 

Module- Abstract short name is T13. 
Father-short-name is T5. 


delete module-abstract in t5; 


or 


delete t13; 


NOTE: If you delete a definition that has other definitions subordinate 
to it, all the subordinate definitions are also automatically deleted. 
For example, if you delete 'SYSTEM MODULES’, you will also delete T6, 
T13, T7, T8, T9, T10, and Til, (See Figure 5 in this section). If the 
definitions you’re trying to delete or any definitions subordinate to it 
has data associated with it, the deletion cannot take place until the 
data has first been deleted. 
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10.6.4 ADD Subcommajid of DEFINE D&TA ^Template Updating) 

Use the ADB subcommand to add a data definition to the template. 


SUBCOHHAND OPEEANDS 


ADD data-def-name, 

[IE f atber-short-name], 
[ data-element— type ], 

[ units-of-measure], 
[repetition-factor], 

[/* explanation */] 


NOTE: if you do not enter the attributes yoor definition ¥ill be 
assigned the following defaults: TEXT, MANY CHAEACTEES, EXACTLY 1 TIMES, 


data— def -name 

the name of the data definition to be added to the template. (For 
rules in creating data-def inition-names see Section 10.4.) 

father — shorf-name 

t.he short name of the data definition to which the data-def inition— 
name to be added is directly subordinate. 

da ta-elemen t- type 

the type of in form ation the data-def inition is. If you do not enter 
a data-element-ty pe, the default is TEXT. (For- format see Section 
10.4.) 

un its- of- me as ur e 

specifies the units of measure of the data definition and any limits 
placed upon fhe size. If you do not enter unit-of-measure, the 
default is MANY CHAEACTEES, (For format see Section 10.4.) 

repetition-factor 

specifies how many times a repeated group many occur. If you do not 
enter a repetition factor, the default is EXACTLY 1 TIMES, (For 
format see Section 10.4.) 
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EXAMPLE 1 

operation: Adding a data definition to the template. 

Xnown: Data-def-name is SYSTEM-ABSTEACT. 

add system-abstract; 


Example 2 

operation: Adding a data definition to the template, 

known: Data-def-name is MODULE- ABSTRACT. 

Father- short-name is T5. 

Data-element-type is TEXT. 
Dnits-of-measure is EXACTLY 2 PAGES. 


add module-abstract in t5, text, exactly 2 pages; 
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10.6.5 CHAUOE Subcommand of DEFINE DATA 


Use the CHANGE subcommand to change part of an entry that already exists 
in the template. 


SDBCOHHAND OPERANDS 


CHANGE old-data-def-name [= ] new-def-name, 

[IN father- short— name], 

[ data-ele ment- type], 

[ units-of-measure ], 

[ repetition-factor ], 

{/* explanation ^/] 


H02E: you do not have to specify old— name = new-name unless you want to 
change the definition name. Otherwise, change [data-def— name IN father- 
short-name] is allowed. Only include those attribute phrases you wish 
to have modified. Whatever you specify will replace what is already in 
the template. 


old- data-def- name 

the data— definition -name to be changed, 
new-def-name 

the data-def inition -name which will .replace the old-data-def inition 
—name. 

father— short— name 

the short name of the data definition to which the data-def initio n- 
name to be changed is directly subordinate, 

data— element-type 

the type of information of the data-def ini tion-name, (Fox format 

see Data Definition Language - Section 10.-4.) 

units- of- mea sure 

specifies the units of measure of the data aefinition and any limits 
placed upon the size. (For format see Data Definition language - 
Section 10.4.) 

repetition-factor 

specifies how many times a repeated group may occur, (For format 
see Data Definition Language - Section 10.4.) 
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EXAMPIE 1 

operatioii: Changing a template entry. 

Jtnown: Old-data-aef-name is SYSTEH-OVEEVIEH. 

New-data-aef-narae is DCSCNIC-OVEEVIEH, 

You wish to change data-element- type to TEXT. 


change system-overview = do’raonic-o verview, text; 


Example 2 

Operation: Same as above, 

known: Data-def-name is HODDLE-TITIE. 

Eather-short-name is T5. 
Dnits-of-measure is MAX 20 CHARACTERS. 

change module-title in t5,. max 20 characters; 
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10.6.6 LIST SubcommaDd of DEEISE DATA {Template Updating) 


Use the LIST subcommand to get a listing of youx template. 


SUBCOBMAKD 



OPERANDS 

LIST 

TEMPLATE 




TE MPLATE 

ATTBIBTJTES 



TEMPLATE 

ATTRIEOTIS 

EXPLANATION 


template 

gives a listing of the data names in the template and 
the associated short names for the active documentation 
unit. 

template attributes 

gives a listing of the data names and their associated 
attributes in the template for the active documentation 
unit, 

template attributes explanation 

gives a listing of the data names, their attributes, and 
their explanations in the template for the active 
documentation unit. 


EXAMPLE 1 

operation: Listing a template. 


list template; 


The system 'will respond by typing out.: 

T^ool sYsrii^^liviEi 

etc. 


Example 2 

operation: listing template attributes. 


list template attributes; 
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The system will respond by typing cnt: 

TO 000 i.s YST E H- oviiv IE w ii~iMOOo 7 ”Tixi 7 *HAx~loooo~iiHEs 

etc. 


Example 3 

operation: Listing tem pi abe-attribnte-ex plana tion. 

i_ 

list template-attributes-explanation; 


The system will respond by typing out: 


TOGO 01 SYSTEH-OVEBVIEW IN TOQOOO, TEXT, HAX 10000 LINES 
/* HORB DESCBIPTION OP THE SYSTEN */ 
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10.6.7 END Suicommand of DEFINE DATA ^Template Updating) 

Use t-he END snbccinmand to end a DEEINS DATA session. Yon may then enter 
another command. 


SOBCOHMAND 


END 


OPEHANDS 


EXAMPLE 1 

operations Terminating a template binding or updating session. 
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TERMINAL CHAE ACTERISTICS 


TELETYPE MODEI 33 TERMINALS 


Keyboa rd: 

Teletype Model 33 -teriiiinals have a four row type writer- like keyboard 
which can generate 96 codes out of a full 128 character ASCII set. 

Printer: 

Teletype Model 33 printers can print 63 characters, including 
uppercase alphabetics, numerics, special symbols and punctuation 
marks. The hOO foot rolls are friction— fed; pin— fed 
is optional. Pages 8.5 inches wide are accepted hy friction-fed. 

Printing is at 10 characters per inch with vertical spacing at 
6 lines per inch. Automatic double spacing can be utilized. 


TELETYPE MODEL 35 TERMINALS 


Keyboard: 

Teletype Model 35 terminals have a four row typewriter-like 
keyboard which can generate 96 characters out of the full 128 
character ASCII set. By depressing ccinbina tions of keys, 
control codes are generated. 

Printer: 

Teletype Model 35 printers accept friction-fed forms from an 
8,5 inch wide, 400 foot roll. Vertical spacing is at 6 lines 
per inch with automatic double spacing possible. Horizontal 
spacing is 10 characters per inch. Automatic double spacing 
is possible. 

A total of 63 characters can be printed, including numerics, 
alphabetics and special symbols. Eor forms up to 9.5 inches, there 
is an optional pin-feed mechanism. 



Page 139 



DOHONIC COMMAND EEiiRINCE MANDAL 
APPENDIX A 


TELETYPE MODEI 37 TEEMINALS 


Keyioards 

Teletype Model 37 terniinals have a four row typeariter 
arrangement. The keyboard can generate 128 graphics and control 
codes of the ASCII character set. To generate the full range, 
shift keys, control and prefix are used in conjunction «ith 
character keys. Any character can be repeated automatically 
by depressing the key below the ncrittal depressed position. 

Printer; 

Teletype Model 37 printers can print 94 (standard) 110 or 
126 symbols of the ASCII graphic set. The horizontal pitch is 
10 characters per inch with a future option of 12 characters 
per inch.' Vertical spacing is 6 lines per inch and operators 
can choose double spacing. 

Standard platen is 8.5 inches wide with friction-feed. Pin-fed 
platen at 9.5 inches wide is opticnal. Options to be announced 
are platens designed to accommcdate forms 3.625 to 9.5 inches 
wide, edge to edge. Bear loading is standard, while front loading 
is optional. Continous forms may be accommodated and stacked in 
the rear- 


TEIETYPE MODEL 38 TEEMINALS 


Keyboard; 

Teletype Model 38 terminals have a four row typewriter 
arrangement. Control codes of ASCII character set and all 128 
graphics can be generated frcm the keyboard. To generate the 
full range, control, shift keys and escape are used in conjunction 
with character keys. Characters can be repeated by automafically 
depressing the key below the normal depressed position. 

Printer; 

Teletype Model 38 printers can print 94 symbols of fhe ASCII 
graphic' set in addition to upper and lowercase alphabetics and 
up to 132 characters per line. Horizontal pitch is 10 characters 
per inch. Vertical spacing is 6 lines per inch and operators 
can choose double spacing- With pin-feed, standard platen 
is 15 inches wide. An option accommcdates friction-feed 8,5 
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inch roll paper and 14 7/8 inch pin-feed forms. 


IBM 1050 DATA COMKQNICATIONS SYSTEM 


Prin ter; 

The 1052 printer- keyboard is built around an IBM Selectric 
ty pew riter. 

When included in the 1050 system, the 1052 carries system switches 
and indicators. There are two models which correspond to the two 
communications models of the 1051 Control Onit. The main 
difference is the insertion of a different set -of switches and 
indicators corresponding to the communications/home-loop 
and communications-only modes of operation of the two 1051 
models. The printer portion and the data entry portion of the 
keyboard for the two models is the same. 

Eighty-eight different symbols including upper and lowercase 
alphabetics at 14.8 or 8.33 characters per second can be 
printed. The printer provides a 15 inch, friction- fed carriage 
with a 13 inch writing line {130 characters) is provided. 

Pin-fed platen is optional. 

Vertical spacing is at either 6 or 8 lines per inch. As an 
option-, the 1052 can be equipped with a vertical form control 
mechanism to allow automatic spacing to predetermined positions 
on a form. A second option speeds the return of the typing 
element on a carriage return by about 50 per cent. 


IBM 2741 COMMUHICATION TEBMINAl 


Keyboard: 

IBM 2741 Communication terminals have a 55 key typewriter style- 
The keyboard can yield any of the 88 upper or lowercase 
alphabetics, numberics and special characters through upper and 
lowercase control codes. Three keyboards are available and 
each corresponds to one of three transmission codes- 

The Typamatic Key option gives a repeat action while the 
hyphen/underscore, backspace and space-bar Jceys are held 
depressed. 
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Prin±er: 

IBM 2741 Communication printers print data from the communications 
facility ox input from the keyboard. 

The rated print speed is 14.8 characters per second and print 
symbols total 88. 

Several interchangeable print elements are available for each 
code. The PTTC/EBCD and PTTC/BCD codes are compatible except 
for punctuation and special symbols. IBH stresses the use of 
identical keyboards and print elements based on the selected 
code for all terminals within the same net»ork. 

Friction-fed or pin-fed (optional) fanfold forms up to 15.5 
inches wide are accoramcdated by the printer. The writing 
width is 13 inches. 

Horizontal spacing can be either 10 or 12 characters per inch. 
Vertical spacing is 6 or 8 (optional) lines per inch, 

IBM stresses the avoidance of intermixing character spacing on 
terminals within the network. 
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SAMPLE EAICH DOB DECK 


//JOBNAME {account inf creation) 

//STEP EXEC DOHONIC 

//SYSIN DD DATA,DCB=BLKSIZE=80 


•{batch input to system) 


Ex planation; 

The system is invoked by the execution of a procedure stored 
in the system procedure library- In the above example this 
procedure is given the name DOHONIC. The SYSIN card identifies 
the batch input to the system. // is in 80 character card 
format and must start vfith a SIGNON command {see format in 
* COMMAND LANGUAGE BEEEBENCE*). 



